02. Integrações - API

Com a integração de API é possível criar um chat totalmente personalizado dentro de seu site ou app.

Para acessar essa funcionalidade vá em Zenvia Chat - Perfil de Administrador > Configurações > Integrações > API.

Para iniciar, basta clicar na aba API, no menu superior e em seguida, preencher os dados da integração no canto direito.

O primeiro campo (superior) gera o token que deve ser inserido no sistema que será integrado. Já no segundo campo (inferior), deve ser incluído o link do sistema integrado.

API de interações

Para obter o token de acesso, vá para: https://zchat-admin.zenvia.com

Então vá para: Menu > Configurações > Integração > API.

⚠️ Atenção: Tome cuidado quando já houver um Token gerado na sua conta para garantir que ele não esteja sendo utilizado em outra integração. Ao gerar um novo Token, qualquer integração vinculada ao anterior deixará de funcionar. Consulte sempre a sua TI ou o responsável pela gestão das suas automações.

Clique em Gerar Token para obter um novo.

Iniciar interação

Faça uma solicitação HTTP POST : https://zchat.zenvia.io/core/api/v1/interactions

Exemplo de corpo:

{
"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	Descrição	Atributos Padrão
token	string	true	Seu token de API	-
media_type	string	false	Tipo de mídia	TEXT, SMS, Instagram, Telegram, WHATSAPP (o null será salvo como TEXT)
department_id	int	true	Id de um departamento ativo de sua conta	-
customer	object	false	Informações do seu cliente	-
name	string	false	Nome do cliente	-
email	string	false	E-mail do cliente	-
phone	string	false	Telefone do cliente	-
cpf	string	false	Documento do cliente	-
extra	object	false	Quaisquer parâmetros (serão retornados no webhook)	-
external_history	string	false	URL que pode OBTER um JSON	-

Resposta de sucesso:
{
"message": "Interaction created successfully",
"data": {
"interaction_hash": "0000a-000b-0c00-0d0e-f00d00f11111"
}
}

Resposta de erro:
{
"message": "Error description here",
"status": 422
}

Interação de atualização

Faça uma solicitação HTTP PUT : https://zchat.zenvia.io/core/api/v1/interactions/{interactionHash}

Parâmetro	Requerido	Descrição	Atributos padrão
interaction_hash	true	ID único para a interação (UUID)	-

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

Parâmetro	Modelo	Requerido	Descrição	Atributos Padrão
token	string	true	Seu token de API	-
media_typeTEXT	string	false	Tipo de mídia	SMS, Instagram, Telegram, WHATSAPP (o null será salvo como TEXT)
department_id	int	true	Id de um departamento ativo de sua conta	-
customer	object	false	Informações do seu cliente	-
name	string	false	Nome do cliente	-
email	string	false	E-mail do cliente	-
phone	string	false	Telefone do cliente	-
cpf	string	false	Documento do cliente	-
extra	string	false	Quaisquer parâmetros (serão retornados no webhook)	-
external_history	string	false	URL que pode OBTER um JSON	-

Resposta de sucesso:
{
"message": "Interaction updated successfully",
"status": 200
}

Resposta de erro:
{
"message": "Error description here",
"status": 422
}

Enviar mensagem
Faça uma solicitação HTTP POST :https://zchat.zenvia.io/core/api/v1/interactions/{interactionHash}/messages

Parâmetro	Requerido	Descrição	Atributos padrão
interaction_hash	true	ID único para a interação (UUID)	-

Exemplo de corpo:
{
"token": "yourAPIToken",
"content": "your message",
"type": "image",
"url": "https://file-address.example.com/logo.png"
}

Parâmetro	Modelo	Requerido	Descrição	Atributos padrão
token	string	true	Seu token de API	-
content	string	true	Sua mensagem	-
type	string	false	Tipo de conteúdo	text, image, video, audio, file (null será salvo como text)
url	string	false	URL do arquivo (exceto para mensagem do tipo "texto")	-

Exemplo de resposta de sucesso:
{
"data": {
"interaction_hash": "0010-abcd-efgh-ijkd-1c422e49fdff"
},
"message": "Message created successfully",
"status": 200
}

Resposta de erro:
{
"message": "Error description here",
"status": 422
}

Notificar quando o cliente digitar

Faça uma solicitação HTTP PUT: https://zchat.zenvia.io/core/api/v1/interactions/{interactionHash}/typing

Parâmetro	Requerido	Descrição	Atributos padrão
interaction_hash	true	Identificação única para a interação (formato UUID)	-

Exemplo de corpo:
{
"token": "YourApiToken"
}

Parâmetro	Modelo	Requerido	Descrição	Atributos padrão
token	string	true	Seu token de API	-

Resposta de sucesso:
{
"message": "Cleared sent successfully",
"status": 200
}

Terminar interação

Faça uma solicitação HTTP PUT : https://zchat.zenvia.io/core/api/v1/interactions/{interactionHash}/finish.

Parâmetro	Requerido	Descrição	Atributos padrão
interaction_hash	true	Identificação única para a interação (UUID)	-

Exemplo de corpo:
{
"token": "YourApiToken"

Parâmetro	Modelo	Requerido	Descrição	Atributos padrão
token	string	true	Seu token de API	-

Resposta de sucesso:
{
"message": "Finish sent successfully",
"status": 200
}

História Externa
Endpoint que RECEBE um JSON:
Resposta:
{
"messages":[
{
"time":"2019-03-14 00:00:01",
"direction":"CLIENT",
"content":"client message here"
},
{
"time":"2019-03-14 00:00:10",
"direction":"AGENT",
"content":"agent answer here"
}
]
}

Parâmetro	Modelo	Requerido	Descrição
messages	array	true	Matriz de objetos de mensagem
time	datetime	true	Quando a mensagem foi gravada
direction	string	true	Quem enviou a mensagem
content		true	Conteúdo da mensagem

Interação adicionada à fila
{
"interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213",
"state": "queued",
"position": 1,
"extra": {}
[
}

Agente aceita interação
{
"interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213",
"state": "accepted",
"extra": {}
}

Em caso de agentes indisponíveis:
{
"interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213",
"state": "unavailable",
"extra": {}
}
Interação final do agente:
{
"interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213",
"state": "finished",
"extra": {}
}

Digitação do agente:
{
"interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213",
"state": "typing",
"extra": {}
}

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

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

Como podemos ajudar?

API de interações

Iniciar interação

Interação de atualização

Terminar interação