04. Zenvia Chat Data API

This API enables querying data from interactions carried out via Zenvia Chat, in accordance with reports currently extracted from the Administration interface.

TOKEN The access token for the API can be generated in the Administration interface through the menu:

Settings
Integrations
API

Link: https://zchat-admin.zenvia.com/integrations

DIGITAL CHANNELS

Equivalent to the Digital Channels report, this allows querying consolidated data regarding the services provided.

Get interactions report:

GET: https://zchat.zenvia.io/api/ms/external/reports?token=yourApiToken

Parameters:

data_type: Determines how the data will be grouped.
period: Time period for the data.
tag: Filter by tags.
department: Filter by department.
channel: Filter by communication channel.
agent: Filter by agent.

Note: If not specified, the default grouping will be by period.

from: Start date of the period, format YYYY-MM-DD HH:MM

e.g., 2021-04-01T06:00:00.
If not specified, the query will search for the last 30 days.
to: End date of the period, format YYYY-MM-DD HH:MM

e.g., 2021-04-30T18:00:00.
If not specified, the query will search until the current date.
timezone: Desired timezone in 5-digit format, e.g., -0300.
If not specified, UTC will be used.
agents: IDs of agents, separated by commas, to filter by specific agents.
If not specified, the search will include all agents.
departments: IDs of departments, separated by commas, to filter by specific departments.
If not specified, the search will include all departments.
states: Filter interactions by specific statuses, e.g., 'ENDED', 'UNAVAILABLE', 'CANCELED', or 'DISCARDED'.
If not specified, the search will include all statuses.
types: Channel through which the interaction took place:
- PHONE - Voice call interactions
- PHONE_CONF - Voice call conferences
- WHATSAPP - WhatsApp interactions
- FACEBOOK - Facebook interactions
- EMAIL - Email interactions
- SMS - SMS interactions
- TELEGRAM - Telegram interactions
- TEXT - Web Chat interactions
- MELI_QST - Mercado Livre questions interactions
- MELI_MSG - Mercado Livre post-sale interactions

Note: If not specified, the search will include all channels.

tags: IDs of tags, separated by commas, to filter interactions with specific tags.

Note: If not specified, the search will include all tags.

Success Response:

{
  "data": [
    {
      "answered": 3,
      "backlog": 14,
      "discarded": 2,
      "ended": 3,
      "expired": 0,
      "made": 0,
      "missed": 0,
      "not_answered": 0,
      "pending": 0,
      "postponed": 0,
      "received": 3,
      "remainder": 12,
      "sla": 17,
      "slapr": 0,
      "title": "2020-02-02",
      "tma": 13,
      "tmaxe": 13,
      "tme": 4,
      "tmp": 0,
      "tmpa": 0,
      "tmpr": 11,
      "tmr": 2
    },
    {
      "answered": 3,
      "backlog": 14,
      "discarded": 2,
      "ended": 3,
      "expired": 0,
      "made": 0,
      "missed": 0,
      "not_answered": 0,
      "pending": 0,
      "postponed": 0,
      "received": 3,
      "remainder": 12,
      "sla": 17,
      "slapr": 0,
      "title": "Total",
      "tma": 13,
      "tmaxe": 13,
      "tme": 4,
      "tmp": 0,
      "tmpa": 0,
      "tmpr": 11,
      "tmr": 2
    }
  ],
  "status": 200,
  "success": true
}

Error Response:

{
  "error": "Error message",
  "status": 401,
  "success": false
}

Variable Definitions:

title: Title
backlog: Previous Backlog (Services that were not completed the previous day)
received: Received (Total new services received during the period)
made: Made (Total services initiated by the agent)
rang: Distributed (Services automatically assigned to the agent)
answered: Answered (Services received by an agent and completed with message exchange)
ended: Ended (Services completed with message exchange and marked as ended by the agent)
not_answered: In Queue (Uncompleted services that were in the queue for service)
pending: Pending (agent) (Services started and placed on the pending list after the last client interaction)
postponed: Pending (client) (Services started and placed on the pending list after the last agent interaction)
discarded: Discarded (Services received by an agent but interrupted without message exchange)
missed: Missed (Inactive services that were closed by the agent)
expired: Expired (Services that expired and can no longer be answered)
remainder: Day's Remainder (Services not finished during the day but can still be completed)
tma: Average Handling Time (seconds)
tme: Average Wait Time (seconds)
tmaxe: Maximum Wait Time (seconds)
tmpr: Average First Response Time (seconds)
tmr: Average Agent Response Time (seconds)
tmpa: Average Time for Agent to Resume a Pending Service (seconds)
tmp: Average Time for Client to Resume a Pending Service (seconds)
sla: Total Average Handling Time (TMA + TME + TMPA) (seconds)
slapr: First Response SLA

Service History

Equivalent to the “Service History” report, this feature allows you to view all data related to interactions, available in both standard and expanded formats.

Get History:

GET: https://zchat.zenvia.io/api/ms/external/history?token=yourApiToken

Get Expanded History:

GET: https://zchat.zenvia.io/api/ms/external/history/expanded?token=yourApiToken

Parameters:

from: Start date of the period, in the format YYYY-MM-DD HH:MM:SS.
Example: 2021-04-01T06:00:00
If not provided, the search will default to the last 30 days.
to: End date of the period, in the format YYYY-MM-DD HH:MM:SS.
Example: 2021-04-30T18:00:00
If not provided, the search will be up to the current date.
timezone: Desired timezone in 5-digit format.
Example: -0300
If not provided, UTC will be used.
active: Determines if the search is for sent or received interactions.
“true” = Sent (interactions initiated by agents).
“false” = Received (interactions initiated by users).
If not specified, the search will include all interactions.
agents: Agent IDs, separated by commas, to search for specific agents.
If not provided, all agents will be searched.
departments: Department IDs, separated by commas, to search for specific departments.
If not provided, all departments will be searched.
states: Search for interactions with specific statuses.
Example: 'ENDED', 'UNAVAILABLE', 'CANCELED', 'DISCARDED'.
If not provided, all statuses will be searched.
- PHONE: Voice call interactions
- PHONE_CONF: Conference call interactions
- WHATSAPP: WhatsApp interactions
- FACEBOOK: Facebook interactions
- EMAIL: Email interactions
- SMS: SMS interactions
- TELEGRAM: Telegram interactions
- TEXT: Web Chat interactions
- MELI_QST: Mercado Livre question interactions
- MELI_MSG: Mercado Livre post-sale interactions
types: Channel through which the interaction occurred.

If not specified, all channels will be searched.

search: Search by client name, agent email, or specific interaction ID.
Example:
search=maria -> Will search for users or agent emails with the field ILIKE '%maria%'
search=999 -> Will search for users or agent emails with the field ILIKE '%999%' or interaction_id=999
limit: Maximum number of interactions per request, limited to 10,000 records.
If not provided, 100 records per request will be displayed.
page: Pagination for records exceeding the limit per request (>=1).
If not provided, only records within the limit of page 1 will be displayed.
Note: A response handler must be applied to verify if the number of records reaches the page limit. In that case, a new request must be made for the next page of records.

Success Response:

{
  "status": 200,
  "success": true,
  "data": [{
    "active": "true/false",  
    "agent": {
      "id": "agent_id",
      "name": "agent_name",
      "phone_extension": "agent_phone_extension"
    },
    "created_at": "created_at_iso",
    "current_state": "status",
    "current_state_time": "current_state_time_iso",
    "customer": {
      "id": "customer_id",
      "fields": {
        "channel_email": ["phone_1", "phone_2"],
        "channel_external": "",
        "channel_facebook": "",
        "channel_mercado_livre": "",
        "channel_phone": "",
        "channel_telegram": "",
        "document": "",
        "main_identifier": "Example",
        "main_photo": ""
      }
    },
    "department": {
      "id": "department_id",
      "name": "department_name"
    },
    "first_answer_time": "first_answer_time_iso",
    "id": "protocol",
    "media": "service_channel",
    "mood": "rating",
    "sla_overdue": true
  }]
}

Error Response:

{
  "error": "Error message",
  "status": 401,
  "success": false
}

Variable Meanings:

expired: Inactive (Interaction expired and can no longer be answered)
expired_time: Inactive Time (Time it took for the inactive interaction to be closed by the agent in seconds)
missed: Missed (Inactive interaction closed by the agent)
canceled: Canceled by the client (Interaction ended by the client before starting)
answered: Completed (Interaction completed by agents)
queued: In Queue (How many times the interaction was queued)
ended: Ended (Interaction with final message exchange closed by the agent)
discarded: Discarded by the agent (Received interaction but interrupted by the agent)
ringing: Distribution (How many times the interaction was distributed among agents)
postponed: Pending (Waiting for client)
(Interaction placed on the pending list after being initiated)
pending: Pending (Waiting for agent)
(Interaction placed on the pending list after client’s last message)
transferring: Transferred (How many times the interaction was transferred)
messages: Total messages (Number of messages exchanged between agent and client)
queued_time: Queue Time (Time the interaction was in the queue or unanswered in seconds)
ringing_time: Distribution Time (Time the interaction was ringing for agents in seconds)
missed_time: Missed Time (Time for inactive interaction to close in seconds)
canceled_time: Cancellation Time (Time until client cancellation in seconds)
talking_time: Interaction Time (Time the interaction was in progress in seconds)
postponed_time: Waiting for client (Time interaction waited for a client message in seconds)
pending_time: Waiting for agent (Time interaction waited for an agent message in seconds)
first_contact_time: Time to first response (Time agent took to respond to the client’s first message in seconds)
response_count: Response Count (Number of exchanges between client and agent)
response_time: Average response time (Average time for agent to respond in seconds)
sla_time: Total interaction time (Time between the client’s first message and the interaction’s completion in seconds)
discarded_time: Time to discard (Time until agent discards interaction in seconds)
browser: Client's browser
ip: Client’s IP address
os: Client’s operating system
source: Source URL (URL that redirected the client to the interaction page)
channel_external: External ID
group_name: Group name
channel_email: Client’s email
channel_phone: Client’s phone number
channel_mercado_livre: Mercado Livre ID
channel_facebook: Facebook ID
channel_telegram: Telegram ID
document: Client’s CPF
main_identifier: Client’s name
agent: Agent who completed the interaction
phone_extension: Agent's phone extension
department: Department responsible for the interaction
endTime: Last update (Date and time of the last status update)
id: Protocol number of the interaction
origin: Who initiated the interaction
startTime: First message (Date and time the first message was received by the agent)
state: Interaction status (Missed or completed)
type: Channel of interaction
tagCount: Number of tags used in the interaction
tags: Tags used in the interaction
mood: Client rating (Satisfaction survey)
notes: Notes
sla_overdue: If the SLA for the first response has exceeded the defined limit, returns true, otherwise false.

Conversation History

To view the message history of a specific conversation, use the command below:

Get Protocol Messages:

GET: https://zchat.zenvia.io/api/ms/external/history/{id}/messages?token=yourApiToken

Parameter:

id: This parameter should be replaced by the protocol number of the desired conversation.

Ongoing Interactions

Allows viewing data of ongoing interactions, equivalent to the “Monitoring,” “Waiting Queue,” “Pending,” and “Inactive” reports.

Get Ongoing Interactions:

GET: https://zchat.zenvia.io/api/ms/external/ongoing?token=yourApiToken

Parameters:

agents: Agent IDs, separated by commas, for searching specific agents.
If not provided, all agents will be searched.
departments: Department IDs, separated by commas, for searching specific departments.
If not provided, all departments will be searched.
states: Search for interactions with specific statuses.
Example: `'NOT_ANSWER', '
types: The channel through which the interaction was conducted:

PHONE - Interactions via voice calls

PHONE_CONF - Voice call conferences

WHATSAPP - Interactions via WhatsApp

FACEBOOK - Interactions via Facebook

EMAIL - Interactions via email

SMS - Interactions via SMS

TELEGRAM - Interactions via Telegram

TEXT - Interactions via Web Chat

MELI_QST - Interactions via questions on Mercado Livre

MELI_MSG - Interactions via post-sales on Mercado Livre

Note: If not specified, the search will include all channels.

limit: The maximum number of interactions per request, with a limit of 10,000 records.
If not specified, 100 records will be presented per request.
page: Pagination for requests exceeding the limit of records per request (>=1).
If not specified, only the records within page 1's limit will be presented.

Note: The response to the request should be processed to validate if the number of records reaches the page limit. In this case, a new request should be made to retrieve the records from the next page.

Successful Response:

{
  "status": 200,
  "success": true,
  "data": [{
    "active": "true/false" (who initiated the contact (sent/received)),
    "agent": {
      "id": "id" (agent_id),
      "name": "name" (agent_name),
      "phone_extension": "phone_extension" (agent_phone_extension),
      "status": "ONLINE/OFFLINE"
    },
    "created_at": "created_at_iso" (interaction created_at),
    "current_state": "status" (interaction last status),
    "current_state_time": "current_state_time_iso" (interaction last status time),
    "customer": {
      "id": "id" (customer id),
      "fields": { (each field can be a string or array (single/multiple fields))
        "channel_email": ["phone_1", "phone2"],
        "channel_external": "",
        "channel_facebook": "",
        "channel_mercado_livre": "",
        "channel_phone": "",
        "channel_telegram": "",
        "document": "",
        "main_identifier": "Example",
        "main_photo": ""
      }
    },
    "department": {
      "id": "department_id",
      "name": "department_name"
    },
    "id": "protocol",
    "media": "service channel",
    "sla_overdue": false
  }]
}

Error Response:

{
  "error": "Error message",
  "status": 401,
  "success": false
}

Hi, Humans. How may we help you?

DIGITAL CHANNELS

Get interactions report:

Success Response:

Error Response:

Variable Definitions:

Service History

Get History:

Get Expanded History:

Parameters:

Success Response:

Error Response:

Variable Meanings:

Conversation History

Get Protocol Messages:

Parameter:

Ongoing Interactions

Get Ongoing Interactions:

Parameters: