Hi, Humans. How may we help you?

02. Integrations API
3 min
Created by Humanz on 6/3/2022 12:25 PM
Updated by Maria Malheiro on 9/18/2024 4:15 PM
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.

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.

Start interaction

 
Make an HTTP POST request to: https://zchat.zenvia.io/core/api/v1/interactions

Example body:


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


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": "[email protected]",
   "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 -
email 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 -


Success response:
{
 "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": {}
}
Did this article solve your doubts?
Recently viewed