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.

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.

 

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

• 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

Ejemplo de respuesta con error

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": {}
}