With API integration, you can create a fully customized chat within your website or app.
To access this functionality, go to Zenvia Chat - Administrator Profile > Settings > Integrations > API.
To get started, simply click on the API tab in the top menu and then fill in the integration details on the right side.
The first field (top) generates the token that should be inserted into the system to be integrated. In the second field (bottom), you should include the link of the integrated system.
To access this functionality, go to Zenvia Chat - Administrator Profile > Settings > Integrations > API.
To get started, simply click on the API tab in the top menu and then fill in the integration details on the right side.
The first field (top) generates the token that should be inserted into the system to be integrated. In the second field (bottom), you should include the link of the integrated system.
Interactions API
To get the access token, go to: https://zchat-admin.zenvia.com
Then go to: Zenvia Chat - Administrator Profile > Settings > Integrations > API.
⚠️ Attention: Be careful if a token has already been generated for your account to ensure that it is not being used in another integration. Generating a new token will disable any integration linked to the previous one. Always consult your IT team or the person responsible for managing your automations.
Click on Generate Token to get a new one.
Then go to: Zenvia Chat - Administrator Profile > Settings > Integrations > API.
⚠️ Attention: Be careful if a token has already been generated for your account to ensure that it is not being used in another integration. Generating a new token will disable any integration linked to the previous one. Always consult your IT team or the person responsible for managing your automations.
Click on Generate Token to get a new one.
Start interaction
Make an HTTP POST request to: https://zchat.zenvia.io/core/api/v1/interactions
Example body:
Example body:
{ "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"}|
Parameter
|
Model | Required | Description | Default Attributes |
|
token
|
string | true | Your API token | - |
| media_type | string | false | Media type |
TEXT, SMS,
Instagram,
Telegram, WHATSAPP
(null will be saved as TEXT)
|
| department_id | int |
true
|
ID of an active department in your account | - |
|
customer
|
object | false | Your customer information | - |
|
name
|
string | false | Customer's name | - |
|
email
</td |
| object | false | Any parameters (will be returned in the webhook) | - | |
|
external_history
|
string | false | URL that can GET a JSON | - |
Successful answer:{ "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"}
Update interaction
Make an HTTP PUT request : https://zchat.zenvia.io/core/api/v1/interactions/{interactionHash}
| Parameter | Required | Description | Default Attributes |
| interaction_hash | true | Unique ID for the interaction (UUID) | - |
Example of a body:
{"token": "YourApiToken", "mood": "POSITIVE", "tag_ids": ["1", "999"], "customer_key": "0010-abcd-efgh-ijkd-1c422e49fdff", "note": "Any note here"}| Parameter | Type | Required | Description | Default Attributes |
| token | string | true | Your API token | - |
| media_typeTEXT | string | false | Media type | SMS, Instagram, Telegram, WHATSAPP (null will be saved as TEXT) |
| department_id | int | true | ID of an active department in your account | - |
| customer | object | false | Customer information | - |
| name | string | false | Customer's name | - |
| string | false | Customer's email | - | |
| phone | string | false | Customer's phone | - |
| cpf | string | false | Customer's document | - |
| extra | string | false | Any parameters (will be returned in the webhook) | - |
| external_history | string | false | URL that can GET a JSON | - |
Success Response: { "message": "Interaction updated successfully", "status": 200}Resposta de erro:{ "message": "Error description here", "status": 422}
Notify when the customer types
Make a request HTTP PUT: https://zchat.zenvia.io/core/api/v1/interactions/{interactionHash}/typing
| Parameter | Required | Description | Default Attributes |
| interaction_hash | true | Unique ID for the interaction (UUID) | - |
Example body:{ "token": "YourApiToken"}
| Parameter | Model | Required | Description | Default Attributes |
| token | string | true | Your token de API | - |
Success response:{ "message": "Cleared sent successfully", "status": 200}
Send a message
Make a request HTTP POST :https://zchat.zenvia.io/core/api/v1/interactions/{interactionHash}/messages
| Parameter | Required | Description | Default Attributes |
| interaction_hash | true | Unique ID for the interaction (UUID) | - |
Example Body:
{"token": "YourApiToken", "mood": "POSITIVE", "tag_ids": ["1", "999"], "customer_key": "0010-abcd-efgh-ijkd-1c422e49fdff", "note": "Any note here"}| Parameter | Model | Required | Description | Default Attributes |
| token | string | true | Your token de API | - |
| content | string | true | Your Message | - |
| type | string | false | Content type | text, image, video, audio, file (null will be saved as text) |
| url | string | false | URL of the file (except for messages of type “text”) | - |
Success response:
{ "message": "Cleared sent successfully", "status": 200}
End interaction
Make an HTTP request PUT : https://zchat.zenvia.io/core/api/v1/interactions/{interactionHash}/finish.
| Parameter | Required | Description | Default Attributes |
| interaction_hash | true | Unique identifier for the interaction (UUID) | - |
Example body:
{ "token": "YourApiToken"}
| Parameter | Model | Required | Description |
Default Attributes
|
| token | string | true | Your API token | - |
{
"message": "Finish sent successfully",
"status": 200
}
External History
Endpoint that RECEIVES a JSON:
Response:
{
"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"
}
]
}
| Parameter | Model | Required | Description |
| messages | array | true | Array of message objects |
| time | datetime | true |
When the message was recorded
|
| direction | string | true |
Who sent the message
|
| content | true | Message content |
Interaction added to queue
{ "interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213", "state": "queued", "position": 1, "extra": {}[}Agent accepts interaction
{ "interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213", "state": "accepted", "extra": {}}In the case of unavailable agents:
{ "interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213", "state": "unavailable", "extra": {}}Final agent interaction:
{ "interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213", "state": "finished", "extra": {}}Agent typing:
{ "interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213", "state": "typing", "extra": {}}Agent stops typing:
{ "interaction_hash": "322e458c-540c-4c11-ab5c-d38d39f57213", "state": "cleared", "extra": {}}New message from the agent:
{ "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": {}}