This is the reference documentation for the Zenvia REST-like API. The API itself is based on resources that are represented by JSON format and are manipulated using the HTTP protocol.

You can send messages through the Zenvia-supported channels.

You can also subscribe to events and receive them on a webhook of your choosing. The available events for each and every channel are:

• Messages: Receive messages events for outgoing and/or incoming messages.
• Messages status: Receive status updates for outgoing messages.

Before using this API you need the following:

• Zenvia Account: create an account on Zenvia platform's site
• Integrations: configure desired channels to send and/or receive messages on the integrations page
• API Token: create an API token on the API console
• Webhook: subscribe to events using subscriptions API resources
  • Status Webhook (important): Since our messaging API is asynchronous, it is necessary to register a webhook in order to know whether the message sending was successful or not.
  • Message Webhook (optional): receive message responses by subscribing to message events.

You can use the Sandbox to start using and testing this API immediately.

You can also access Zenvia platform to view your Usage Report

The fastest way to begin utilizing this API is with our Sandbox (available on the Zenvia platform).

As you create your new Sandbox, you'll be guided step-by-step in order to start sending and receiving messages using your desired channel.

Click here and start sending and receiving messages using RCS, WhatsApp or SMS using this API.

You are allowed to send test messages to phone numbers you've connected during a 24-hour period. Following that, you must reconnect your number by sending the keyword once again to continue using the Sandbox's features.

All breaking changes to Zenvia APIs will be documented here.

Currently, the Zenvia APIs is on version v2.

• Breaking Changes
  • Visitor not sent as a JSON within contents block. Instead, it's sent directly under the message object.
  • Location is no longer used as JSON.
  • Removed deprecated channels attribute from the template resource.

You can still check v1 version clicking here.

Make it simpler to use our API by integrating our SDK into your software.

These helper libraries are available on Node and Java programming languages and located on our GitHub page.

HTTP methods are used to manipulate resources. Though, as not all resources allow all HTTP operations, observeOK the reference of each resource below.

Methods used with collection endpoints:

HTTP Method	Operation	Success HTTP status
GET	List collection items	200 - OK
POST	Create a new item	200 - OK

Methods used with item endpoints:

HTTP Method	Operation	Success HTTP status
GET	Retrieve one resource item	200 - OK
DELETE	Delete one resource item	204 - No content
PATCH	Update one resource item	200 - OK

When an operation is executed successfully, the API will respond with a 2xx status code.

When one error occurs, the API will return a 4xx or 5xx HTTP status code and the payload with an Error Object.

The error object obeys the follwing schema:

Responses error codes are detailed below.

Http Status Code	Code	Message	Retry request
400	VALIDATION_ERROR	Validation error	No
401	AUTHENTICATION_ERROR	No authorization token was found	No
404	NOT_FOUND	Not found	No
409	DUPLICATED	Entity already exists	No
500	INTERNAL_ERROR	Internal error	Yes

To use this API you need to send the API token in every request.

The token needs to be sent in the HTTP header X-API-TOKEN.

Example:

X-API-TOKEN: hKp94crjv9OF3UGrCpSXUJw1-UYHhRvLKNLt

Generate your token on the API console on Zenvia platform.

This is an advanced version of the token authentication.

In this approach, alongside the X-API-Token http header, it is necessary to send a request signature.
The signature is expected in the X-API-Signature http header.

This signature needs to be generated for each request, since it is unique to the request.

Although similar, the standard token do not support signature, and the signature token always requires a signature.
Both types of token can be created in the API console on Zenvia platform.

Example:

X-API-Token: hKp94crjv9OF3UGrCpSXUJw1-UYHhRvLKNLt
X-API-Signature: rtHTyAfsJFD5UFpPDeztUI3JE0Guea5pqG9iJqrT2EY=

Signature generation

The signature is a HMAC-SHA256 hash, calculated using the token secret obtained at the creation of the signature token in the API console, encoded as a base64 string.

The input for the hash generation is a multiline string, composed by six lines separated by unix line breaks: \n, without an empty line in the end.

The components of each line are the following:

1. The request method.
   Ex: POST, GET.

2. The MD5 hash of the request body.
   Ex: d98bd30dcb3c03d166eee84efba1e3d7

   • For request without body, this line must be empty.
   • For multipart/form-data, only the file content from the request is expected for the hash calculation.

3. The request Content-Type header.
   Ex: application/json.

   • For request without body, this line must be empty.
   • For multipart/form-data, the file content type should be used.

4. The request Date header, formatted following the RFC2616.
   Ex: Sun, 12 Feb 2023 07:40:32 GMT.

   • Timestamps in the future will not be considered valid.
   • Timestamps older than 3 minutes will be refused.

5. The request hostname. It probably will always be api.zenvia.com.
   Ex: api.zenvia.com.

6. The request resource, including the query string when present.
   Ex: /v2/channels/whatsapp/messages, /v2/files?limit=5.

Signature input examples

POST
d98bd30dcb3c03d166eee84efba1e3d7
application/json
Sun, 12 Feb 2023 07:40:32 GMT
api.zenvia.com
/v2/channels/whatsapp/messages

GET


Sun, 12 Feb 2023 07:40:32 GMT
api.zenvia.com
/v2/files?limit=5

Signature generation example in JavaScript

const crypto = require('crypto');

const payload = JSON.stringfy({
  from: 'sms-account',
  to: '55108888888888',
  contents: [{
    type: 'text',
    text: 'Hi Zenvia!',
  }],
});

const date = new Date().toUTCString();
const contentType = 'application/json';

const stringToSign = `POST
${crypto.createHash('md5').update(payload).digest('hex')}
${contentType}
${date}
api.zenvia.com
/v2/channels/sms/messages`;

const token = '123456';
const secret = 'ABCDEF';

const signature = crypto.createHmac('sha256', secret).update(stringToSign).digest('base64');

const headers = {
  Date: date,
  'Content-Type': contentType,
  'X-API-Token': token,
  'X-API-Signature': signature,
}

console.log(headers);

The JWT token is primarily used by front-end applications for user interactions.

For server-to-server integrations use the token authentication approach.

For each content type covered in the next section, the following table reflects its support for each available channel:

Content Type	SMS	Facebook	WhatsApp	RCS	Voice	Telegram	GBM*	Instagram	E-Mail
text	✔	✔	✔	✔	✕	✔	✔	✔	✕
file	✕	✔	✔	✔	✕	✔	✔	✔	✕
replyable_text	✕	✔	✕	✔	✕	✕	✔	✔	✕
template	✔	✕	✔	✔	✕	✕	✕	✕	✔
card	✕	✔	✕	✔	✕	✕	✔	✔	✕
carousel	✕	✔	✕	✔	✕	✕	✔	✔	✕
contacts	✕	✕	✔	✕	✕	✕	✕	✕	✕
location	✕	✕	✔	✕	✕	✕	✕	✕	✕
call	✕	✕	✕	✕	✔	✕	✕	✕	✕
email	✕	✕	✕	✕	✕	✕	✕	✕	✔
button	✕	✕	✔	✕	✕	✕	✕	✕	✕
list	✕	✕	✔	✕	✕	✕	✕	✕	✕
product_list	✕	✕	✔	✕	✕	✕	✕	✕	✕
product	✕	✕	✔	✕	✕	✕	✕	✕	✕

*GBM stands for Google Business Messages

This type of content is the most used one and is composed of plain text.

This type of content is used to send a file to the user. Depending on the file type, the file itself will be displayed with a different appearance. There are four types of presentation:

• Image
• Video
• Audio
• Document

This is the same as text content, but is followed by buttons for quick replying.

This type of content has an underlying fixed text content with some required variables. With the fields of the template properly filled, the template must be submitted for approval. This approval depends solely on WhatsApp, and the criteria are strict.

Submitting a template content for approval

You may submit templates for approval using our template console if you already own a WhatsApp Business account with us.

This type of content is rich and is composed of at least one of the following components (none of them are mandatory):

• Media
• Title
• Text

Additionally, it may include:

• Buttons
• Quick reply buttons (not part of the card itself, but are instead shown below it)

More information on each attribute may be found below:

This type of content displays a horizontally scrollable sequence of cards, with some differences and limitations.

More details may be found below.

This type of content is used to send contact information to the user.

This type of content is used to send location messages represented as a point on the map to the user.

This is the Voice channel content.

This is the E-Mail channel content.

This the SMS version of the text content. It has additional parameters specific to the SMS integration.

Single product message. This is a WhatsApp channel content.

Product list message. This is a WhatsApp channel content.

This is Instagram and Facebook recurring message optin request content.

This is Whatsapp Product List Order content. This is supported only in the webhook content.

This is Instagram and Facebook recurring message optin response content. This is supported only in the webhook content.

The SMS channel may be used after its activation on Zenvia platform.

Get in touch with Zenvia consultants to create your account.

Webhooks allow you to receive events in the configured URL. Learn more here.

SMS length

A SMS has a maximum length of 140 bytes, which can be used either with the standard encoding, which supports 160 characters (7 bits each), or using an unicode encoding, which supports 70 characters (16 bits each).

Character support

The standard encoding supports around 110 different characters, while the unicode encoding supports around 65500 characters.
Here are some examples of characters which are only supported by the unicode encoding:
çÇáéíóúýÁÉÍÓÚÝàèìòùÀÈÌÒÙãõñäëïöüÿÄËÏÖÜÃÕÑâêîôûÂÊÎÔÛºª°|

Encoding selection

By default, our API selects automatically the SMS encoding based on the message content.
However, it is also possible to enforce an encoding strategy. More details can be found in the SMS Text section.

Concatenated SMS

To overcome the SMS size limitation, cellphone manufacturers developed a feature called concatenated SMS.
This allows a long message to be break down into multiple SMS messages for delivery, which are joined back together by the cellphone SMS application.

Therefore, when a message is longer than 160 characters in the standard encoding or 70 characters in the unicode encoding, this feature will be applied automatically.

Important things to keep in mind:

• Longer messages means more cost, because they actually are multiple messages.
• To identify each piece of the message, some bytes are used as a header in this feature, so each message piece is shorter than a single short message:
  • Up to 152 characters in the standard encoding and up to 66 characters in the unicode encoding.
  • The cut point currently is always a space, so some pieces might be smaller than this.
  • Combine the previous limitations, and words longer than the maximum characters in a message piece are not supported (152 characters in the standard encoding and 66 characters in the unicode encoding).
• Not all carriers support this feature. The bigest carriers support it, namely: Vivo, Claro, Tim and Oi.
• Double spaces and tabs will always be replaced by a single space.
• To send long messages, it might be necessary to contact our service team and request that this feature be enabled on your account.
• The maximum length currently supported is 1520 characters.

When you send a message to a contact using SMS channel:

• Recipient: the complete phone number (including country code) of the contact.
• Sender: the SMS account alias connected on Zenvia platform.

When you receive a message from a contact, the sender and recipient are inverted:

• Recipient: the SMS account alias connected on Zenvia platform.
• Sender: the complete phone number (including country code) of the contact.

The sender goes in the attribute from and the receiver goes in the attribute to of message object.

The WhatsApp channel may be used after its activation on Zenvia platform.

To activate WhatsApp you a need a registered number on WhatsApp Business API and an account registered on Zenvia platform.

Get in touch with Zenvia consultants to create your account.

Webhooks allow you to receive events in the configured URL. Learn more here.

The WhatsApp API has some limitations:

• To start a conversation with someone you need a specific type of message caled a template message, which requires approval before being used.

• Messages not being as template content type, can only be delivered inside a 24-hour window since the last sent message by the client to the company.

• When sending PNG images with a transparent background, you can get an unexpected final result due to the image processing performed by WhatsApp in order to convert the image to JPEG.

Supported content types and sizes:

Media	Content Type	Post-Processing Media Size*
document	Any valid MIME type.	100 MB
image	image/jpeg image/png	5 MB
sticker	image/webp Note: Animated sticker is not supported.	100 KB
audio	audio/acc audio/mp4 audio/amr audio/mpeg audio/ogg; codecs=opus Note: The base audio/ogg type is not supported.	16 MB
video	video/mp4 video/3gpp Notes: Only H.264 video codec and AAC audio codec is supported. Only videos with a single audio stream are supported.	16 MB

*The size of the media file after encryption. The maximum file size for media that can be uploaded is 64MB.

When you send a message to a contact using WhatsApp channel:

• Recipient: the phone number of the contact
• Sender: the WhatsApp sender id registered on Zenvia platform

When you receive a message from a contact, the sender and recipient are inverted:

• Recipient: the WhatsApp sender id registered on Zenvia platform
• Sender: the phone number of the contact

The sender goes in the attribute from and the receiver goes in the attribute to of message object.

The Instagram channel may be used after its activation on Zenvia Platform.

Get in touch with Zenvia consultants to connect your account.

To be able to send messages to a contact, you first need to setup a webhook, which will allow you to receive events in the configured URL. Learn more here.

• The response window is 24 hours, with the exception when a human agent is replying the contact, then the response window is increased to 7 days.

The Instagram API content type and size limitations for sending media:

Media	Content Type	Media Size
image	image/jpeg image/png image/ico image/bmp image/webp image/*	8 MB
audio	audio/*	Currently not supported
video	video/*	Currently not supported
document	Any other valid MIME type.	Currently not supported

When you receive a message from a contact from Instagram channel:

• Recipient: your Instagram account id (not your account @)
• Sender: the contact id on your account (not the contact @ and it will differ across accounts)

When you send a message to a contact, the sender and recipient are inverted:

• Recipient: the contact id on your account (not the contact @ and it will differ across accounts)
• Sender: your Instagram account id (not your account @)

The sender goes in the attribute from and the receiver goes in the attribute to of message object.

The Facebook channel may be used after you connect a Facebook page on Zenvia platform.

To be able to send messages to a contact, you first need to setup a webhook, which will allow you to receive events in the configured URL. Learn more here.

When you receive a message from a contact from Facebook channel:

• Recipient: your Facebook page id
• Sender: the contact id on your Facebook page (PSID - page scoped id)

When you send some message to a contact, the sender and recipient are inverted:

• Recipient: the contact id on your Facebook page (PSID - page scoped id)
• Sender: your Facebook page id

The sender goes in the attribute from and the receiver goes in the attribute to of message object.

The RCS channel may be used after its activation on Zenvia platform.

Get in touch with Zenvia consultants to create your Google agent (a conversational entity that interacts with users by sending messages and reacting to users' responses).

Webhooks allow you to receive events in the configured URL. Learn more here.

Rich Communcation Services, or RCS for short, is a messaging protocol similar to SMS, where it's used by telecommunications providers as a standard of messaging. In practical terms, the messaging process is similar to SMS:

Unlike the traditional text messaging format (SMS), RCS significantly introduces a range of dynamic features. Suggested actions and replies enable users to engage in conversations more efficiently, offering contextually relevant options based on the message content. With the integration of cards and carousels, users can share interactive content, such as location maps, images, and links, seamlessly within the chat interface. The protocol also supports read receipts, delivery receipts, and typing indicators, providing users with real-time visibility into the status of their messages.

Check out visually how these RCS features look here.

The RCS channel is compatible only with Android smartphones with 8.0 version (Oreo) or above. Most Android devices already come with RCS enabled.

The use of RCS channel follows Google's content policies, available through this link: https://developers.google.com/business-communications/rcs-business-messaging/support/tos.

When you send a message to a contact using RCS channel:

• Recipient: the phone number of the contact
• Sender: the agent id configured on Zenvia platform

When you receive a message from a contact, the sender and recipient are inverted:

• Recipient: the agent id configured on Zenvia platform
• Sender: the phone number of the contact

The sender goes in the attribute from and the receiver goes in the attribute to of message object.

RCS Verfied Senders

RCS business messaging (or RBM for short) allows a business with a Google-provided RBM agent to send RCS messages to mobile end-users. This agent is associated with branding and business information, such as a logo, description, webistes, brand name, and more. The Verified Sender Badge of your brand tells mobile end-users that they can trust that sender given Google's clearance. Along with the badge, there are some additional features that an RBM agent can send to a mobile end-user in comparison to traditional text messaging.

RCS Events Receipts

RCS enables instantaneous interaction through real-time event handling. Agents and users exchange delivery receipts, read receipts, and typing indicators, ensuring prompt acknowledgment and response tracking. User activities automatically trigger events, while agents can actively send updates, keeping users informed about message acknowledgment and response progress. This real-time engagement elevates the responsiveness and overall user experience within RCS conversations.

RCS Suggested Actions and Suggested Replies

Within RCS, diverse messaging formats contribute to a rich and adaptable communication landscape. From conventional text messages to multimedia-rich content like images and videos, RCS caters to a variety of communication needs. Suggested replies, suggested actions, and interactive suggestion chip lists further enhance the conversational experience. These versatile messaging formats provide the flexibility needed to craft engaging and natural conversations.

We've separated the specific attributes of Rich Cards and Carousels in distinct sections below, highlighting their unique functionalities and how they add to the overall versatility of RCS messaging.

RCS Rich Cards

Rich Cards in RCS provide a straightforward way to convey information, media, or suggestions in a unified format. These cards, which can be presented individually or in a carousel, offer a practical means of sharing content. With the ability to include various elements such as media, text, and interactive options, Rich Cards serve as a functional tool for delivering diverse content without unnecessary complexity.

RCS Carousel

Carousels in RCS offer a dynamic way to present a sequence of rich cards, enhancing the user experience with visual appeal. Each card within the carousel can be customized to display different content, providing a simple and interactive method for sharing information. Carousels are designed for practicality, offering a user-friendly approach to conveying a series of related messages or content pieces.

The Telegram can be used after its activation on Zenvia platform.

To activate Telegram you a need a registered Bot account on Telegram Bot API and an account enabled on Zenvia platform.

To be able to send messages to a contact, you first need to setup a webhook, which allows you to receive events in the configured URL. Learn more here.

Supported content types and sizes:

Media	Content Type	Size
image	image/*	5 MB
video	video/*	20 MB
audio	audio/*	20 MB
document	Any other valid MIME type.	20 MB

When you receive a message from a contact from Telegram channel:

• Recipient: the Telegram bot username enabled on Zenvia platform://app.zenvia.com/home/credentials/telegram/list)
• Sender: the conversation id (not the phone number)

When you send a message to a contact, the sender and recipient are inverted:

• Recipient: the conversation id (not the phone number)
• Sender: the Telegram bot username enabled on Zenvia platform://app.zenvia.com/home/credentials/telegram/list)

The sender goes in the attribute from and the receiver goes in the attribute to of message object.

The Google Business Messages channel may be used after its activation on Zenvia platform.

To activate Google Business Messages you need to be registered as a partner with Google Business Messages and get an account information configured on Zenvia platform.

Get in touch with Zenvia consultants to create your account.

To be able to send messages to a contact, you first need to setup a webhook, which allows you to receive events in the configured URL. Learn more here.

When you receive a message from a contact from Google Business Messages channel:

• Sender: the agent id configured on Zenvia platform
• Recipient: the contact id

When you send a message to a contact, the sender and recipient are inverted:

• Recipient: the contact id
• Sender: the agent id configured on Zenvia platform

The sender goes in the attribute from and the receiver goes in the attribute to of message object.