Hola, Humans. ¿En qué podemos ayudarte?

02. Integraciones - API
11 min
Creado por Humanz en 03/06/2022 12:25
Actualizado por Leonora Alves en 18/09/2024 16:15
Con la integración de la API es posible crear un chat totalmente personalizado dentro de su sitio web o aplicación.

Para acceder a esta funcionalidad, vaya a Zenvia Chat - Perfil de Administrador > Ajustes > Integraciones > API.




Para comenzar, solo haga clic en la pestaña API en el menú superior y luego complete los datos de la integración en la esquina derecha.

El primer campo (superior) genera el token que debe ser insertado en el sistema que será integrado. En el segundo campo (inferior), debe incluir el enlace del sistema integrado.

API de integraciones

Para obtener el token de acceso, vaya a: https://zchat-admin.zenvia.com

Luego, vaya a:  Menú > Ajustes > Integraciones > API.

⚠️ Atención: Tenga cuidado cuando ya exista un Token generado en su cuenta para asegurarse de que no esté siendo utilizado en otra integración. Al generar un nuevo Token, cualquier integración vinculada al anterior dejará de funcionar. Consulte siempre con su TI o el responsable de la gestión de sus automatizaciones.

Haga clic en  Generar Token  para obtener uno nuevo.

Iniciar interacción

 
Realice una solicitud HTTP POST: https://zchat.zenvia.io/core/api/v1/interactions

Ejemplo de cuerpo:

{
 "token": "YourApiToken",
 "media_type": "TEXT",
 "department_id": 9999,
 "customer": {
   "name": "Name Surname",
   "email": "[email protected]",
   "phone": "11991417777",
   "cpf": "12345678900"
 },
 "extra" : {
   "clientId": "1",
   "botId": "1111"
 },
 "external_history": "https://chat-history.example.com"
}


Parámetro
Modelo Requerido Descripción Atributos Predeterminados
token
 
string true Su token de API -
media_type string false Tipo de medio
TEXT, SMS,
Instagram,
Telegram, WHATSAPP
(o null se guardará como TEXT)
department_id int
true
 
Id de un departamento activo en su cuenta -
customer
 
object false Información de su cliente -
extra
 
object false Información adicional -
external_history string false Enlace de historial de interacciones con el cliente -

Ejemplo de respuesta

 
La respuesta es un json con los siguientes campos:
  • success: Indica si la interacción se ha creado correctamente (booleano).
  • message: Mensaje de confirmación en caso de éxito.
  • error: Mensaje de error en caso de falla.
  • error_type: Tipo de error en caso de falla.

Ejemplo de respuesta exitosa

 
{
 "success": true,
 "message": "Interaction created successfully"
}

Ejemplo de respuesta con error

 
{
 "success": false,
 "error": "Invalid Token",
 "error_type": "INVALID_TOKEN"
}
Teléfono del cliente-cpfstring falseDocumento del cliente -extrastring falseCualquier parámetro (será devuelto en el webhook) -external_historystring falseURL que puede OBTENER un JSON -

Respuesta de éxito:
{
   "message": "Interacción actualizada con éxito",
   "status": 200
}

Respuesta de error:
{
   "message": "Descripción del error aquí",
   "status": 422
}

Actualización de Interacción
Realiza una solicitud HTTP PUT: https://zchat.zenvia.io/core/api/v1/interactions/{interactionHash}

Parámetro Requerido Descripción Atributos estándar
interaction_hash verdadero ID único para la interacción (UUID) -


Ejemplo de cuerpo:

{
"token": "YourApiToken",
"mood": "POSITIVE",
"tag_ids": ["1", "999"],
"customer_key": "0010-abcd-efgh-ijkd-1c422e49fdff",
"note": "Any note here"
}

Parámetro Modelo Requerido Descripción Atributos estándar
token string verdadero Tu token de API -
media_type string falso Tipo de medio SMS, Instagram, Telegram, WHATSAPP (o null será guardado como TEXT)
department_id int verdadero ID de un departamento activo en tu cuenta -
customer object falso Información de tu cliente -
name string falso Nombre del cliente -
email string falso Correo electrónico del cliente -
phone string falso Teléfono del cliente -
cpf string falso Documento del cliente -
extra string falso Cualquier parámetro (serán retornados en el webhook) -
external_history string falso URL que puede OBTENER un JSON -


Respuesta de éxito:
{
"message": "Interacción actualizada con éxito",
"status": 200
}

Respuesta de error:

{
"message": "Descripción del error aquí",
"status": 422
}

Enviar mensaje
Realiza una solicitud HTTP POST: https://zchat.zenvia.io/core/api/v1/interactions/{interactionHash}/messages

Parámetro Requerido Descripción Atributos estándar
interaction_hash verdadero ID único para la interacción (UUID) -


Ejemplo de cuerpo:

{
"token": "yourAPIToken",
"content": "your message",
"type": "image",
"url": "https://file-address.example.com/logo.png"
}
Parámetro Modelo Requerido Descripción Atributos estándar
token string verdadero Tu token de API -
content string verdadero Tu mensaje -
type string falso Tipo de contenido text, image, video, audio, file (null será guardado como text)
url string falso URL del archivo (excepto para mensajes de tipo "texto") -


Ejemplo de respuesta de éxito:

{
"data": {
"interaction_hash": "0010-abcd-efgh-ijkd-1c422e49fdff"
},
"message": "Mensaje creado con éxito",
"status": 200
}

Respuesta de error:

{
"message": "Descripción del error aquí",
"status": 422
}

Notificar cuando el cliente escribe
Realiza una solicitud HTTP PUT: https://zchat.zenvia.io/core/api/v1/interactions/{interactionHash}/typing

Parámetro Requerido Descripción Atributos estándar
interaction_hash verdadero Identificación única para la interacción (formato UUID) -


Ejemplo de cuerpo:

{
"token": "YourApiToken"
}

Parámetro Modelo Requerido Descripción Atributos estándar
token string verdadero Tu token de API -


Respuesta de éxito:

{
"message": "Notificación enviada con éxito",
"status": 200
}


Terminar interacción

Realiza una solicitud HTTP PUT: https://zchat.zenvia.io/core/api/v1/interactions/{interactionHash}/finish

Parámetro Requerido Descripción Atributos estándar
interaction_hash verdadero Identificación única para la interacción (UUID) -


Ejemplo de cuerpo:

{
"token": "YourApiToken"
}

Parámetro Modelo Requerido Descripción Atributos estándar
token string verdadero Tu token de API -


Respuesta de éxito:

{
"message": "Finalización enviada con éxito",
"status": 200
}

Historia Externa
Endpoint que RECIBE un JSON: Respuesta:

{
"messages": [
{
"time": "2019-03-14 00:00:01",
"direction": "CLIENT",
"content": "mensaje del cliente aquí"
},
{
"time": "2019-03-14 00:00:10",
"direction": "AGENT",
"content": "respuesta del agente aquí"
}
]
}

Parámetro Modelo Requerido Descripción
messages array verdadero Matriz de objetos de mensaje
time datetime verdadero Cuándo fue grabado el mensaje
direction string verdadero Quién envió el mensaje
content string verdadero Contenido del mensaje


Interacción añadida a la cola:

{
"interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213",
"state": "queued",
"position": 1,
"extra": {}
}

Agente acepta la interacción:

{
"interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213",
"state": "accepted",
"extra": {}
}

En caso de agentes no disponibles:

{
"interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213",
"state": "unavailable",
"extra": {}
}

Interacción final del agente:

{
"interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213",
"state": "finished",
"extra": {}
}

Escritura del agente:

{
"interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213",
"state": "typing",
"extra": {}
}

Agente deja de escribir:

{
"interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213",
"state": "cleared",
"extra": {}
}

Nuevo mensaje del agente:

{
"interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213",
"message": {
"hash": "3110a5da-87c7-4f6d-a4ab-2b1ed5edfd46",
"content": "Mensaje",
"type": "text",
"url": "http://..."
},
"agent": {
"id": 111,
"name": "Atendente"
},
"extra": {}
}

¿Este artículo ha resuelto sus dudas?
Vistos recientemente