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
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
Ejemplo de cuerpo:
{
"token": "YourApiToken",
"media_type": "TEXT",
"department_id": 9999,
"customer": {
"name": "Name Surname",
"email": "name@example.com",
"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
- 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"
}
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 | - |
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": {}
}