image1
image 2
**Read:** containing only YES/NO \ **Read at:** containing date and time it was opened \ **Billing type:** indicating whether the message is Basic / Single and in cases where it only has a dash (-), it means that we are talking about an SMS message. \ **Sent as SMS (if there was a fallback to SMS):** Yes/No \ **Message parts:** number of parts that were sent
| Image | Up to 2MB |
| Video | Up to 10MB |
| URL (website button) | URL length limit is 2048 characters |
| Image | Up to 1MB |
| Video | Up to 5MB |
| URL | URL length limit is 2048 characters |
Data from the current month, excluding the current day.
Example: If today is April 8, it will display data from April 1 to April 7.
Data from the previous month, excluding the current month.
Example: If the current month is April, it will display data from March.
Data from the last two months, excluding the current month.
Example: If the current month is April, it will display data from February and March.
* Most of the existing filters have been retained. * RCS Analytics introduces new filters, such as:
* **Status Description**, which provides more detailed information about your message status; * **Message Type**, allowing you to distinguish between rich cards, carousels, and text messages; * **Sender ID**.
* The **Shortcode** filter is no longer available, as subaccounts can now be configured by shortcode. * Filters such as **Scheduled For**, **Read**, **Created At**, and **original\_UUID** are no longer available. The information they provided is already covered by the current filters available in RCS Analytics. # Username (BSUID - coming soon!) The **Username** feature is Meta's latest release, which enables customers to seamlessly initiate WhatsApp conversations with your business without revealing their personal phone numbers, by utilizing a unique username. Given that each individual has a unique WhatsApp username, Meta generates a corresponding BSUID (Business-Scoped User ID). This BSUID serves as an internal identifier created exclusively for the relationship between that person and your business. ### How it works? Users who do not adopt usernames, will continue be identifiable by their phone numbers, while users who do adopt usernames will be identifiable to the business by a BSUID. If a user adopts a username, their phone number will no longer be visible to businesses. Instead, that user can choose to proactively share it with a business if needed. ### Update Guide: User Interface Changes #### 1. Contact Import The contact management screen and the upload spreadsheet have been updated to support Meta's new identifier. * **New Table Column:** The default view of your contact list now includes a dedicated column for the **BSUID** alongside the traditional phone number. * **Contact Spreadsheet Upload:** Within the import wizard, the first column (`Destination`) has been made more flexible: * It continues to accept traditional phone numbers. * It now also accepts the **BSUID** directly as a destination. * For WhatsApp dispatches, clients can include the BSUID information in the same column as the phone number or add a dedicated secondary column.
| Error | Description | Solution |
|---|---|---|
An error occurred while processing this request. Please try again later. | Business account creation could have failed due to various reasons, please contact Support for further assistance. | Use an active Facebook account or contact Support for resolution. |
You have reached the limit for the number of Businesses you can create at this time. | There is a limit to the number of Business Accounts that you can create. | Please use an existing Business Account. |
Your Facebook account is too new to create a business account. Try again in an hour. | New Facebook accounts have to wait for some time to create a Business Manager account. | Use an existing active Facebook account or wait for a few hours before using your new account. The new Facebook account can be actively used during the wait period. |
| We limit how often you can post, comment or do other things in a given amount of time in order to help protect the community from spam. You can try again later. | Your Facebook account was been flagged because of suspicious behavior. | Use an existing, active Facebook account with no prior issues. |
You’re no longer allowed to use Facebook Products to advertise. You can’t run ads, manage advertising assets or create new ad or business accounts. | You are unable to create new Business Manager accounts due to previous suspicious behavior. | Use an existing, active Facebook account with no prior issues. |
The name you chose for your business isn’t valid. Consider using xxx. | Invalid business name. | Add a valid name that matches the name of your business. |
A user can only create one business user at a time | You can only create a single Business Account within a given time period. | Use an existing Business Account to onboard. |
{{1}}
How are you? Below are your ticket details:
| | **Your flight to the city of {{3}} is scheduled for {{4}}, at {{5}}. Have a nice trip!** |{{2}}
{{3}}
Make sure to write down your flight details so you don’t forget:
{{4}}
{{5}}
| ### Template Rejected? What Could Be the Reason? **You are not allowed to send promotional content** i.e., all types of offers that **have not been requested by the customer.** There are certain words that lead FB’s approval team to believe that a template is promotional, even when its content does not have that intention**:** **Price reductions/changes** * Promotion; * Promotional; * Promo; * Offer; * Proposal; * Sale; * Discount; * Bargain; * Deal; * Advantage; * Clearance; * Steal; * Markdown; **Advertising and news** * Ad * Advertising * Propaganda * Commercial * Release * Limited edition * Promote * Publicity * Opportunity **Gratuities** * Sample * Coupon * Lottery * Gift * Surprise * Freebie * Giveaway ### Examples of Rejected Messages | | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Did you know you have a pre-approved loan of {{1}}? You can pay it back in up to {{2}} installments, and the money is credited to your account within 24 hours after approval! Don’t miss it! This offer is available until {{3}}.** | | | | **Hi, {{1}}! How are you? We have great news! You are only one click away from contracting your loan. Just reply to this message and we can help you!** | | | | **This is the Digital Assistant speaking on behalf of {{2}} store. We noticed you are interested in {{3}}, at the {{4}} portal. How about simulating a loan, scheduling a test drive, or speeding up your used car review? Just click the link: {{5}}** | | | |We have news for you! In order to check it out for free and get ready to increase your sales, enter:
1 - to see the {{3}} collection;
2 - to receive the {{2}} catalog.
| | | | **We have a proposal for you! Can we chat here right now?** | ## Opening a Session A session is the 24-hour period from the moment you receive a message from your user. That is, **only MOs (messages sent by your customer) open a session.** You must send a template to start the conversation and, from the moment your user replies, the session is open and you can directly communicate with them without requiring a new template. You can send free texts, pictures, attachments, videos. ## A Few Expressly Forbidden Actions #### **Messages of a promotional, advertising, or invasive nature (spam)** Message templates regarding **Sales; Marketing; Promotions.** Any actions of a spamming nature are forbidden. For everything you do in this channel, always keep in mind that the end customer is who decides if you are helping, informing, or bothering them. Thus, we suggest a communication that is always centered on the end consumer. ## **Template Suggestions** **1: General information (very similar to collecting an opt-in in the channel)** Hello! We would like to inform you that this is the official channel for XXXXX. You can use this channel to XXXXXXX. Click the "Yes, I want it!" button to begin receiving messages or "Exit" if you are not interested: Buttons: Yes, I want it! / Exit **2: Assistance for people who wish to purchase products / services, ensure their opt-in is collected on the actual website, and when the base is less than 3 days old.** Hello, we noticed you have signed up for our website. We would like to let you know that this is our WhatsApp channel, and we can answer any questions you may have here. Click the "Yes, I want it!" button to learn more or "Exit" if you are not interested: Buttons: Yes, I want it! / Exit **3: Bank slips / invoices** Hello, this is the official channel for the XXX company for information on invoices payable or overdue / order status / account status. Click the "Yes, I want it!" button to begin receiving messages or "Exit" if you are not interested: Buttons: Yes, I want it! / Exit **4: Order status** Hello, this is the official channel for XXXX for information and order statuses. Click the "Yes, I want it!" button to begin receiving messages or "Exit" if you are not interested: Buttons: Yes, I want it! / Exit **5: Consigned credit / Loans** Hello, this is the official channel for XXXX, here you can ask any questions and learn more about XXXXXXX. Click the "Yes, I want it!" button to learn more or "Exit" if you are not interested: Buttons: Yes, I want it! / Exit ### **Automatic Replies:** **EXIT:** Your request to leave the conversation was accomplished. Please send #start to come back! **#START:** Your request to return to this conversation was accomplished! Welcome back! **YES:** **1: General information (very similar to collecting an opt-in in the channel)** Thank you, you will receive this information here, stay tuned. **2: Assistance for people who wish to purchase products / services, ensure their opt-in is collected on the actual website, and when the base is less than 3 days old.** Thank you, we will contact you soon to answer your questions Thank you, send a Hi to begin your assistance **3: Bank slips / invoices** Thank you, you will receive this information here, stay tuned. **4: Order status** Thank you, you will receive the status of your order(s) here, stay tuned. **5: Consigned credit / Loans** Thank you, we will contact you through the channel soon to better assist you. It’s great having you here. We will always keep you informed through this channel, and whenever you need us, just let us know # Deleting a WA Template You can delete a template that has been approved, is under approval, or has been denied by WhatsApp through the Messaging platform. **How To:** On the template list, click the trash can and await the 30 days of confirmation by WhatsApp to create a new template with the same name as the one you deleted. You cannot send a template after it has been deleted.  # WhatsApp Account Settings Learn how and what you can change in your WhatsApp profile {% hint style="info" %} After all the process of creating a WhatsApp account, it is possible to carry out all the management of WhatsApp information within the Sinch Messaging platform. {% endhint %} ## **Editing Your WhatsApp Profile** {% hint style="danger" %} **BE CAREFUL! Changes will be made instantaneously!** {% endhint %} {% hint style="success" %} **What you are allowed to change:** * Your Company’s industry * Status * Description * Address * Website * Facebook or Instagram page * Email * Picture {% endhint %} {% hint style="danger" %} **What you are not allowed to change:** * Your Company’s name; * Phone number; {% endhint %} ## **How to Manage Your WhatsApp Account:**  ### **Account on Mobile Device:**  # WhatsApp Dashboard Learn more details about your WhatsApp Dashboard ## **WhatsApp Dashboard** This is where you see general and detailed information on messages triggered to WhatsApp  ### **Field descriptions** * Total messages: This is where you can view the total number of messages sent and received within a selected period. * Date filter: It is located on the upper right corner; just select the period you wish to filter. * Total MTs: Total number of messages sent. * Sent: Messages that have left for delivery on the platform. * Sent with open session: These are the messages that have been sent and delivered to devices, where the end user replied to your message. * Sent with closed session: These are messages that have been sent and delivered to devices, but your end user did not reply to your message. * Delivered: Messages that have been sent and delivered to devices. * Read: Number of messages according to the stipulated filter that have been read by your end users; a point of attention is that we only have this status if your end user has the read receipt enabled. * Total MOs: Number of messages your end users have sent to your company. * Session-opening MOs: Number of users who contacted your company, without any interaction from you. * Under Open Sessions Now you have the data of live open sessions. ### **Overview** To access this field, just switch the tab on your screen:  {% hint style="info" %} **Overview** This is where you can filter your charts to better review your triggers View * Time * Day of the Month * Month Charts * Total MTs * Sent * Delivered * Read * Total MOs Additionally, you can also filter by **Campaigns, Subaccounts and Users.** {% endhint %} # Tech Providers - What is it and how does it work? The Tech Provider refers to companies that need, in a legitimate way, to access commercial data from other organizations to offer services or functionalities to them. Here, we can understand it as Reseller companies. No app claimed by a company can be used by other companies until the verification as a Tech Provider is completed. Account Admins can finalize the verification process for the company to be recognized as a Tech Provider. Once verified, any app claimed by the customer can be used by another customer of this reseller. ## How does it work? If you are a Reseller company, it is necessary to have an ISV (Independent Software Vendor) registration directly in Meta's BM (Business Manager). The administrative part of the process is first carried out in your BM, either by you or you can request support from our Support team. Once this is done, you can proceed with the Embedded SignUp process. Remember that if it is necessary to create other customers on the Messaging platform (MM2), you should contact our Provisioning team (Support)! ## How to do it: step by step 1. You (Reseller) must have access to the BM as an Admin and be an ISV. 2. It is necessary to have an app within this BM (to learn more about how it works, see [here](https://developers.facebook.com/docs/development/create-an-app/)). As a Reseller (ISV), it is required that this BM be verified by Meta. 3. Make sure your app is in "live" mode and not in development mode. If this is not set up this way, you will receive an error in the embedded signup process. The app is created by default in development mode, and you can switch the mode on the app's page. 4. Once everything is set correctly in the app, it is important that you are connected to our Sinch app. If you don't have it, go to the left sidebar of the BM, click on Partner Solutions, and then click to create a Partner Solution. Next, you should define a name for the solution (internal) and add the Sinch AppID in the Partner app ID field. The Partner app ID varies based on the BM to which we will connect the number (to access this partner app ID, contact our support and inform them that you are going through the Tech Provider process on your own). 5. After you follow these steps, we at Sinch must accept the partnership solution request on the partnership solutions page of our app! Once accepted, just continue with the embedded signup process. If you need to create more customers in your reseller or need support in this process, simply reach out to our Provisioning team (Support)! # Business-scoped user IDs Learn about using business-scoped user IDs with LATAM Messaging's WhatsApp channel In mid-2026, Meta will allow WhatsApp users to adopt usernames. Prior to this feature rollout, WhatsApp users will be assigned a corresponding business-scoped user ID. LATAM Messaging customers may use this business-scoped user ID to identify recipients when using LATAM Messaging. Additionally, for some contacts that adopt usernames later in 2026, the business-scoped user IDs may be the only identifier available. Business-scoped user ID information will begin to be included in LATAM Messaging callbacks in March of 2026. When using LATAM Messaging, you are able to identify your message recipients by setting the `destination`. The `destination` value has historically been a phone number. With the release of WhatsApp's business-scoped user ID functionality, you will also be able to use business-scoped user IDs as identifiers. These will take the form of `CONTACT_country_code.unique_alphanumeric_string` (for example, `US.13491208655302741918`) as `destination` values when specifying your recipient in LATAM Messaging calls. You can collect business-scoped user IDs from certain LATAM Messaging callbacks, which will be updated to include these business-scoped user IDs. In order to successfully make use of WhatsApp business-scoped user IDs, you must know how to: * [Incorporate business-scoped user IDs into your API calls](#including-business-scoped-user-ids-in-api-calls) * [Retrieve business-scoped user ID information from LATAM Messaging callbacks](#retrieving-business-scoped-user-id-information-from-callbacks) * [Manage how phone numbers and business-scoped user IDs relate to one another](#managing-phone-numbers-and-business-scoped-user-ids-using-contact-book) ### Including business-scoped user IDs in API calls If you already know your contact's business-scoped user ID, you may use it to identify them in any LATAM Messaging call that identifies recipients through the `destination` field. For example, to send a message to a recipient using their business-scoped user ID as identification, you would use a payload of the following form: ``` { "destinations": [ { "destination": "CONTACT_business_scoped_user_ID" } ], "message": { "button": { "body": { "text": "Hello from Latam API! I'm the body text." }, "footer": { "text": "Hello from Latam API! I'm the footer text." }, "buttons": [ { "reply": { "title": "I'm the title!", "payload": "I'm the payload!" } } ] } } } ``` {% hint style="info" %} Note the following: * Business-scoped user IDs are unique for each contact and are scoped to individual business service providers. Attempts to reach a contact through one business service provider by using a corresponding business-scoped user ID retrieved from another business service provider will fail. * You cannot use business-scoped user IDs to send one-tap, zero-tap, or copy code authentication template messages. If you attempt to send one of these messages using a business-scoped user ID, the corresponding status report will have a `sentStatus` of `CARRIER_COMMUNICATION_ERROR`. {% endhint %} The immediate response you receive after making your API call will be the same regardless of whether you use phone numbers of business-scoped user IDs to send the message. ### Retrieving business-scoped user ID information from callbacks Business-scoped user ID information may be included in different LATAM Messaging webhooks, including webhooks that make use of the `destination` field (for example, status webhooks) or the `source` field (for example, message inbound webhooks). This information will begin to be included in LATAM Messaging webhooks in March of 2026. {% hint style="info" %} Note: If, for any reason, LATAM Messaging is able associate a contact with a phone number, the phone number will be included as the `destination` or `source` value for webhooks associated with that contact. {% endhint %} Additional information will be included in the `userProfile` object. A description of this object, along with webhook examples, are provided in the subsections below. #### Business-scoped user ID information in the status webhooks If you send a message to a recipient after March of 2026, status callbacks (i.e., delivery reports) will include business-scoped user ID information. Below are examples of status webhooks. The tab that is selected by default displays a delivery report for a message sent using a business-scoped user ID. The alternate tab displays a delivery report for a message sent using a recipient's phone number and, therefore, does not include business-scoped user ID information in the `destination` field: {% tabs %} {% tab title="Business scoped user ID" %} ``` { "total": 1, "data": [ { "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91", "correlationId": "...", "destination": "CONTACT_business_scoped_user_ID", "userProfile": { "name": "CONTACT_name", "username": "CONTACT_username", "countryCode": "BR", "userId": "CONTACT_business_scoped_user_ID", "parentUserId": "PARENT_business_scoped_user_ID" }, "origin": "YOUR_phone_number", "campaignId": 100, "campaignAlias": "...", "flowId": "...", "extraInfo": "...", "sent": true, "sentStatusCode": 1, "sentStatus": "sent status", "sentDate": "2017-12-18T17:09:31.891Z", "sentAt": 1513616971891, "delivered": true, "deliveredStatusCode": 1, "deliveredStatus": "delivered status", "deliveredDate": "2017-12-18T17:09:31.891Z", "deliveredAt": 1513616971891, "read": true, "readDate": "2017-12-18T17:09:31.891Z", "readAt": 1513616971891, "updatedDate": "2017-12-18T17:09:31.891Z", "updatedAt": 1513616971891, "type": "MESSAGE", "conversation": { "id": "conversationId123", "origin": { "type": "REFERRAL_CONVERSION" }, "expiration": "2017-12-19T17:09:31.891Z" } } ], "clientInfo": { "customerId": 42, "subAccountId": 1291, "userId": 1 } } ``` {% endtab %} {% tab title="Phone number" %} ``` { "total": 1, "data": [ { "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91", "correlationId": "...", "destination": "CONTACT_phone_number", "userProfile": { "name": "CONTACT_name", "username": "CONTACT_username", "countryCode": "BR", "phoneNumber": "CONTACT_phone_number", "userId": "CONTACT_business_scoped_user_ID", "parentUserId": "PARENT_business_scoped_user_ID" }, "origin": "YOUR_phone_number", "campaignId": 100, "campaignAlias": "...", "flowId": "...", "extraInfo": "...", "sent": true, "sentStatusCode": 1, "sentStatus": "sent status", "sentDate": "2017-12-18T17:09:31.891Z", "sentAt": 1513616971891, "delivered": true, "deliveredStatusCode": 1, "deliveredStatus": "delivered status", "deliveredDate": "2017-12-18T17:09:31.891Z", "deliveredAt": 1513616971891, "read": true, "readDate": "2017-12-18T17:09:31.891Z", "readAt": 1513616971891, "updatedDate": "2017-12-18T17:09:31.891Z", "updatedAt": 1513616971891, "type": "MESSAGE", "conversation": { "id": "conversationId123", "origin": { "type": "REFERRAL_CONVERSION" }, "expiration": "2017-12-19T17:09:31.891Z" } } ], "clientInfo": { "customerId": 42, "subAccountId": 1291, "userId": 1 } } ``` {% endtab %} {% endtabs %} Note the following: * The callback includes new information in the `userProfile` object. The existing field (`name`) and each new field (`username`, `countryCode`, `phoneNumber`, `userId`, and `parentUserId`) are described in the table below:| Field | Required? | Description | | -------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `username` | No | The username is included if the end-user activates the username feature. | | `countryCode` | Yes (`countryCode` will begin appearing in webhooks starting March 31, 2026). | Present when `userId` BSUID is set; its value is the first two characters of the BSUID containing the country code. | | `phoneNumber` | No | The MSISDN (phone number) of the contact. Because contacts can be identified using the business-scoped user ID, this field is not required. | | `userId` | Yes (business-scoped user IDs will begin appearing in webhooks starting March 31, 2026) | The business-scoped user ID. | | `parentUserId` | No | Parent business-scoped user IDs can be used in place of regular businses-scoped user IDs to message users. Functionally, parent business-scoped user IDs have the same properties as regular business-scoped user IDs, but they can be used by any business phone number within a given set of linked portfolios. | * The `phoneNumber` field of the `userProfile` object is **not** included in the business-scoped user ID example. If the phone number for that contact was known, it would be set as the `destination` *and* included in the `userProfile` object. * Because the phone number of the contact is known in the phone number example, the `destination` is set to the phone number. The business-scoped user ID is included in the `userId` field of the `userProfile` object. #### Business-scoped user ID information in the inbound messages webhook Below are examples of inbound message callbacks. The tab that is selected by default displays an inbound message received from a WhatsApp contact with a username and no associated phone number. The alternate tab displays an inbound message from a contact associated with a phone number in your LATAM Messaging solution: {% tabs %} {% tab title="Business scoped user ID" %} ``` { "total": 1, "data": [ { "id": "ce425ffe-bc62-421f-9261-e6819a5eab43", "source": "CONTACT_business_scoped_user_ID", "origin": "...", "userProfile": { "name": "CONTACT_name", "username": "CONTACT_username, "countryCode": "BR", "userId": "CONTACT_business_scoped_user_ID", "parentUserId": "CONTACT_business_scoped_user_ID" }, "campaignId": 100, "correlationId": "...", "campaignAlias": "...", "flowId": "....", "extraInfo": "...", "message": { "type": "TEXT", "messageText": "Hi, this is a message from the contact" }, "receivedAt": 1513616971473, "receivedDate": "2017-12-18T17:09:31.473Z" } ] } ``` {% endtab %} {% tab title="Phone number" %} ``` { "total": 1, "data": [ { "id": "ce425ffe-bc62-421f-9261-e6819a5eab43", "source": "CONTACT_phone_number", "origin": "...", "userProfile": { "name": "CONTACT_name", "username": "CONTACT_username, "countryCode": "BR", "phoneNumber": "CONTACT_phone_number" "userId": "CONTACT_business_scoped_user_ID", "parentUserId": "CONTACT_business_scoped_user_ID" }, "campaignId": 100, "correlationId": "...", "campaignAlias": "...", "flowId": "....", "extraInfo": "...", "message": { "type": "TEXT", "messageText": "Hi, this is a message from the contact" }, "receivedAt": 1513616971473, "receivedDate": "2017-12-18T17:09:31.473Z" } ] } ``` {% endtab %} {% endtabs %} Note the following: * The callback includes new information in the `userProfile` object. The existing field (`name`) and each new field (`username`, `countryCode`, `phoneNumber`, `userId`, and `parentUserId`) are described in the table below:
| Field | Required? | Description | | -------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `username` | No | The username is included if the end-user activates the username feature. | | `countryCode` | Yes (`countryCode` will begin appearing in webhooks starting March 31, 2026). | Present when `userId` BSUID is set; its value is the first two characters of the BSUID containing the country code. | | `phoneNumber` | No | The MSISDN (phone number) of the contact. Because contacts can be identified using the business-scoped user ID, this field is not required. | | `userId` | Yes (business-scoped user IDs will begin appearing in webhooks starting March 31, 2026) | The business-scoped user ID. | | `parentUserId` | No | Parent business-scoped user IDs can be used in place of regular businses-scoped user IDs to message users. Functionally, parent business-scoped user IDs have the same properties as regular business-scoped user IDs, but they can be used by any business phone number within a given set of linked portfolios. | * The `phoneNumber` field of the `userProfile` object is **not** included in the business-scoped user ID example. If the phone number for that contact was known, it would be set as the `source` *and* included in the `userProfile` object. * Because the phone number of the contact is known in the phone number example, the `source` is set to the phone number. The business-scoped user ID is included in the `userId` field of the `userProfile` object. ### Managing phone numbers and business-scoped user IDs using contact book Beginning in early April 2026, Meta will release a [contact book feature](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#contact-book) that will automatically collect and associate business-scoped user IDs with phone numbers for contacts to whom you have sent or from whom you have received a message using the contact's telephone number. This association will be passed to LATAM Messaging. Therefore, any contact you communicate with via phone number will, from that point on, be associated with the phone number and corresponding business-scoped user ID in your LATAM Messaging solution.
sent success from Latam is equivalent to
message\_delivery\_report.status = QUEUED\_ON\_CHANNEL in Conv API
delivered success from Latam is equivalent to
message\_delivery\_report.status = DELIVERED in Conv API
read from Latam is equivalent to
message\_delivery\_report.status = READ in Conv API
failed from Latam is equivalent to
message\_delivery\_report.status = FAILED in Conv API
If
message\_metadata
Optional.
channel\_metadata not present on QUEUED\_ON\_CHANNEL status.
| | `data[*].userProfile.whatsAppId` | `channel_identity.identity` | channelIdentity always filled in Sinch webhooks. | | `data[*].userProfile.name` | `channel_metadata.whatsapp.user_profile.display_name` |Optional.
channel\_metadata not present on QUEUED\_ON\_CHANNEL status.
| | `data[*].userProfile.username` | `channel_metadata.whatsapp.userProfile.username` |Optional.
channel\_metadata not present on QUEUED\_ON\_CHANNEL status.
| | `data[*].userProfile.countryCode` | `channel_metadata.whatsapp.user_profile.country_code` |Optional.
channel\_metadata not present on QUEUED\_ON\_CHANNEL status.
| | `data[*].userProfile.phoneNumber` | `channel_metadata.whatsapp.user_profile.phone_number` |Optional.
channel\_metadata not present on QUEUED\_ON\_CHANNEL status.
| | `data[*].userProfile.userId` | `channel_metadata.whatsapp.userProfile.userId` |Optional.
channel\_metadata not present on QUEUED\_ON\_CHANNEL status.
| | `data[*].userProfile.parentUserId` | `channel_metadata.whatsapp.user_profile.parent_user_id` |Optional.
channel\_metadata not present on QUEUED\_ON\_CHANNEL status.
| *** #### 3) Status update callback (Latam) **3.1) Base status fields** | **Latam field** | **Conv API field** | **Notes** | | --------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `data[*].id` | `message_delivery_report.messageId` | Converted from ULID to UUID format before output. | | `data[*].destination` | `message_delivery_report.channelIdentity.identity` | Recipient identity. | | `data[*].origin` | `channel_metadata.whatsapp.senderPhoneNumber` | Fallback lookup may be used when missing. | | `data[*].type` | `-` | No dedicated direct field. | | `data[*].updatedDate` | `event_time` | In Sinch there’s no concept of updated webhook times, we treat each one independently of each other. | | `data[*].updatedAt` | `event_time` | In Sinch there’s no concept of updated webhook times, we treat each one independently of each other. | **3.2) Delivery/sent/read flags and timestamps** | **Latam field** | **Conv API source** | **Notes** | | ----------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------- | | `data[*].sentStatus` | `message_delivery_report.status` (+ `reason.code` for FAILED) | `QUEUED/DELIVERED/READ -> SENT_SUCCESS`; `FAILED -> fromConvStatus`. | | `data[*].sentStatusCode` | `-` | No dedicated direct field. | | `data[*].sent` | `-` | Equivalent to `message_delivery_report.status=SENT` being triggered. | | `data[*].deliveredStatus` | `-` | No dedicated direct field. | | `data[*].deliveredStatusCode` | `-` | No dedicated direct field. | | `data[*].delivered` | `-` | Equivalent to `message_delivery_report.status=DELIVERED` being triggered. | | `data[*].read` | `-` | Equivalent to `message_delivery_report.status=READ` being triggered. | | `data[*].sentDate` | `message_delivery_report.status=SENT` event\_time | In Conv API it is only present in SENT status. | | `data[*].sentAt` | `message_delivery_report.status=SENT event_time` | In Conv API it is only present in SENT status. | | `data[*].deliveredDate` | `message_delivery_report.status=DELIVERED event_time` | In Conv API it is only present in DELIVERED status. | | `data[*].deliveredAt` | `message_delivery_report.status=DELIVERED event_time` | In Conv API it is only present in DELIVERED status. | | `data[*].readDate` | `message_delivery_report.status=READ event_time` | In Conv API it is only present in READ status. | | `data[*].readAt` | `message_delivery_report.status=READ event_time` | In Conv API it is only present in READ status. | *** #### 4) MO callback (message sent by end user) **4.1) Base MO fields** | **Latam field** | **Conv API field** | **Notes** | | ---------------------- | ----------------------------------------------- | ------------------------------------- | | `data[*].id` | `-` | No dedicated direct field. | | `data[*].source` | `message.channel_identity.identity` | End-user source identity. | | `data[*].origin` | `channel_metadata.whatsapp.sender_phone_number` | Business phone number. | | `data[*].messageId` | `message_delivery_report.message_id` | Optional link to original MT message. | | `data[*].receivedDate` | `eventTime` | Time of the event. | | `data[*].receivedAt` | `eventTime` | Time of the event. | | `data[*].mtSentAt` | `-` | No dedicated direct field. | *** #### 5) MO message payload mapping by message type **5.1) Text MO** | **Latam field** | **Conv API field** | | --------------- | ------------------ | | **Latam field** | **Conv API field** | | ------------------------------- | ---------------------------------------------------- | | `data[*].message.type = "TEXT"` | Infered by contact\_message subtype = text\_message. | | `data[*].message.messageText` | `message.contact_message.text_message.text` | **5.2) Media MO (image/video/audio/document/sticker)** | **Latam field** | **Conv API field** | **Notes** | | -------------------------- | ------------------------------------------- | ----------------------------------------------------- | | `data[*].message.type` | `message.contact_message.media_message` | Infered by contact\_message subtype = media\_message. | | `data[*].message.mediaUrl` | `message.contact_message.media_message.url` | Media strategy. | | `data[*].message.mimeType` | `-` | No dedicated direct field. | **5.3) Media-card MO** | **Latam field** | **Conv API field** | | -------------------------- | ----------------------------------------------------- | | `data[*].message.type` | Infered by contact\_message subtype = media\_message. | | `data[*].message.mediaUrl` | `message.contact_message.media_card_message.url` | | `data[*].message.mimeType` | `-` | | `data[*].message.caption` | `message.contact_message.media_card_message.caption` | **5.4) Location MO** | **Latam field** | **Conv API field** | | ----------------------------------- | ---------------------------------------------------------------------- | | `data[*].message.type = "LOCATION"` | Infered by contact\_message subtype = media\_message. | | `data[*].message.location.geoPoint` | `message.contact_message.location_message.coordinates` as `"lat,long"` | | `data[*].message.location.address` | `message.contact_message.location_message.label` | | `data[*].message.location.name` | `message.contact_message.location_message.title` | **5.4) Location MO** | **Latam field** | **Conv API field** | | ----------------------------------- | -------------------------------------------------------------------- | | `data[*].message.type = "LOCATION"` | Infered by contact\_message subtype = mediaMessage. | | `data[*].message.location.geoPoint` | `message.contactMessage.locationMessage.coordinates` as `"lat,long"` | | `data[*].message.location.address` | `message.contactMessage.locationMessage.label` | | `data[*].message.location.name` | `message.contactMessage.locationMessage.title` | Check [WhatsApp Message Support | Conversation API | Sinch](https://developers.sinch.com/docs/conversation/channel-support/whatsapp/message-support#receiving-delivery-receipts) and [WhatsApp Message Support | Conversation API | Sinch](https://developers.sinch.com/docs/conversation/channel-support/whatsapp/message-support#receiving-messages) for the complete Conv API Documentation. *** ### Failed Status Webhook Errors #### Native Conversation API **Error Fields in Conv API** Based on the Meta’s error code (check [Developer Platform](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)) or in our WhatsApp Internal Processing, we may encounter failures which will trigger the failed status webhook. When that happens, we will trigger a message\_delivery\_report status webhook with the following failure object: **Reason Object** | **Reason Field** | **Description** | | ---------------- | ------------------------------------------------------------------------- | | `code` | `Internal Conv API Error Code.` | | `description` | `Error Description. Will be Meta's error message in case of Meta Errors.` | | `subCode` | `For WhatsApp, always "UNSPECIFIED_SUB_CODE"` | | `channelCode` | `Meta Error Code, if applicable.` | **FAILED Status Webhook Payload Example** ``` { "app_id":"{{app_id}}", "accepted_time":"2026-05-25T18:00:07.205Z", "event_time":"2026-05-25T18:00:08.670147319Z", "project_id":"{{project_id}}", "message_delivery_report":{ "message_id":"01KSG4PJ95QVFVGDHHSHV9DQCG", "conversation_id":"", "status":"FAILED", "channel_identity":{ "channel":"WHATSAPP", "identity":"{{destination_phone_number}}", "app_id":"" }, "contact_id":"", "reason":{ "code":"TEMPLATE_NON_EXISTING_LANGUAGE_OR_VERSION", "description":"The underlying channel reported: Message: (#132001) Template name does not exist in the translation (type: OAuthException, code: 132001, details: template name (invalid_test) does not exist in en_US)", "sub_code":"UNSPECIFIED_SUB_CODE", "channel_code":"132001" }, "metadata":"", "processing_mode":"DISPATCH" }, "message_metadata":"", "correlation_id":"", "channel_metadata":{} } ``` You may use the table below to see all possible *code* and *channel\_code* values that can be returned inside the *reason* obejct: **Possible Error Values** | **Error** | **ReasonCode** | **Channel Code** | | --------------------------------------- | ---------------------------------------------- | ---------------- | | FALLBACK\_ERROR | INTERNAL\_ERROR | -1 | | AUTH\_EXCEPTION | CHANNEL\_BAD\_CONFIGURATION | 0 | | API\_UNKNOWN | CHANNEL\_FAILURE | 1 | | API\_SERVICE | CHANNEL\_FAILURE | 2 | | API\_METHOD | CHANNEL\_REJECT | 3 | | API\_TOO\_MANY\_CALLS | RATE\_LIMITED | 4 | | API\_PERMISSION\_DENIED | CHANNEL\_REJECT | 10 | | INVALID\_PARAMETER | BAD\_REQUEST | 100 | | ACCESS\_TOKEN\_EXPIRED | CHANNEL\_REJECT | 190 | | API\_PERMISSION\_NOT\_GRANTED | CHANNEL\_REJECT | 200-299 | | TEMPORARILY\_BLOCKED\_POLICY\_VIOLATION | CHANNEL\_FAILURE | 368 | | DUPLICATED\_POST | CHANNEL\_REJECT | 506 | | RATE\_LIMIT\_ISSUE | RATE\_LIMITED | 80007 | | MEDIA\_DOWNLOAD\_ERROR | MEDIA\_NOT\_REACHABLE | 131052 | | MEDIA\_UPLOAD\_ERROR | BAD\_REQUEST | 131053 | | PAYMENT\_ISSUE | CHANNEL\_REJECT | 131042 | | MESSAGE\_EXPIRED | CHANNEL\_REJECT | 131043 | | USER\_NUMBER\_PART\_OF\_EXPERIMENT | RECIPIENT\_NOT\_REACHABLE | 130472 | | RATE\_LIMIT\_HIT | RATE\_LIMITED | 130429 | | UNSIGNED\_CERTIFICATE | CHANNEL\_REJECT | 131045 | | SERVICE\_OVERLOADED | CHANNEL\_FAILURE | 131016 | | RE\_ENGAGEMENT\_MESSAGE | OUTSIDE\_ALLOWED\_SENDING\_WINDOW | 131047 | | SPAM\_RATE\_LIMIT | DELIVERY\_REJECTED\_DUE\_TO\_POLICY | 131048 | | META\_CHOSE\_NOT\_TO\_DELIVER | CHANNEL\_FAILURE | 131049 | | GENERIC\_ERROR | CHANNEL\_FAILURE | 131000 | | MESSAGE\_TOO\_LONG | BAD\_REQUEST | 131001 | | INVALID\_RECIPIENT\_TYPE | BAD\_REQUEST | 131002 | | ACCESS\_DENIED | CHANNEL\_REJECT | 131005 | | RESOURCE\_NOT\_FOUND | BAD\_REQUEST | 131006 | | REQUIRED\_PARAM\_MISSING | BAD\_REQUEST | 131008 | | PARAMETER\_VALUE\_NOT\_VALID | BAD\_REQUEST | 33, 131009 | | BAD\_USER | RECIPIENT\_INVALID\_CHANNEL\_IDENTITY | 131021 | | MESSAGE\_UNDELIVERABLE | RECIPIENT\_NOT\_REACHABLE | 131026 | | SENDER\_ACCOUNT\_LOCKED | CHANNEL\_REJECT | 131031 | | UNSUPPORTED\_MESSAGE\_TYPE | BAD\_REQUEST | 131051 | | METHOD\_NOT\_ALLOWED | CHANNEL\_REJECT | 131055 | | PAIR\_RATE\_LIMIT\_HIT | RATE\_LIMITED | 131056 | | ACCOUNT\_MAINTENANCE | CHANNEL\_FAILURE | 131057 | | TEMPLATE\_PARAM\_COUNT\_MISMATCH | BAD\_REQUEST | 132000 | | TEMPLATE\_DOES\_NOT\_EXIST | TEMPLATE\_NON\_EXISTING\_LANGUAGE\_OR\_VERSION | 132001 | | TEMPLATE\_TEXT\_TOO\_LONG | BAD\_REQUEST | 132005 | | TEMPLATE\_FORMAT\_POLICY\_VIOLATED | BAD\_REQUEST | 132007 | | TEMPLATE\_PARAMETER\_FORMAT\_MISMATCH | BAD\_REQUEST | 132012 | | TEMPLATE\_PAUSED | CHANNEL\_REJECT | 132015 | | TEMPLATE\_DISABLED | CHANNEL\_REJECT | 132016 | | FLOW\_BLOCKED | CHANNEL\_REJECT | 132068 | | FLOW\_THROTTLED | CHANNEL\_REJECT | 132069 | | DELETE\_INCOMPLETE | INTERNAL\_ERROR | 133000 | | DECRYPTION\_ERROR | CHANNEL\_FAILURE | 133001 | | BACKUP\_BLOB\_DECRYPTION\_ERROR | CHANNEL\_FAILURE | 133002 | | RECOVERY\_TOKEN\_DECRYPTION\_ERROR | CHANNEL\_FAILURE | 133003 | | SERVER\_TEMPORARILY\_UNAVAILABLE | CHANNEL\_FAILURE | 133004 | | SECURITY\_PIN\_MISMATCH | CHANNEL\_REJECT | 133005 | | PHONE\_NUMBER\_REVERIFICATION\_NEEDED | CHANNEL\_REJECT | 133006 | | ACCOUNT\_BLOCKED | CHANNEL\_REJECT | 133007 | | TOO\_MANY\_PIN\_GUESSES | CHANNEL\_REJECT | 133008 | | PIN\_GUESSED\_TOO\_FAST | CHANNEL\_REJECT | 133009 | | PHONE\_NUMBER\_NOT\_REGISTERED | CHANNEL\_REJECT | 133010 | | GENERIC\_USER\_ERROR | CHANNEL\_REJECT | 135000 | #### Comparing to Latam Errors In Latam, we have the following errors: [WhatsApp API | Sinch | Latam Messaging Documentation](https://docs-latam.messaging.sinch.com/technical-documentation/api-and-integrations/whatsapp-api#errors) Since there’s no direct mapping between Latam ↔︎ Conv API error codes, in case you need to identify and handle a specific error, you may check the Channel Code Reason in the table above to identify and treat it accordingly. ### Other Statuses Webhooks Examples #### SENT STATUS **LATAM** ``` { "total" : 1, "data" : [ { "id" : "c67f724a-2e70-4b43-b8e0-5b2f4862d427", "destination" : "{{destination_phone_number}}", "origin" : "{{business_phone_number}}", "sent" : true, "sentStatusCode" : 2, "sentStatus" : "SENT_SUCCESS", "sentDate" : "2024-04-02T17:20:19.389Z", "sentAt" : 1712078419389, "updatedDate" : "2024-04-02T17:20:19.630Z", "updatedAt" : 1712078419630, "type" : "MESSAGE" } ], "clientInfo" : { "customerId" : {{customer_id}}, "subAccountId" : {{sub_account_id}} } } ``` **CONV API** ``` { "app_id": "{{app_id}}", "accepted_time": "2025-11-26T17:23:08.614Z", "event_time": "2025-11-26T17:23:09.657218958Z", "project_id": "{{project_id}}", "message_delivery_report": { "message_id": "01KB0K1FP6HTG4W9EJV6YYFH3G", "conversation_id": "01JQ6RN9DTAMF5HXBZKQE90WXT", "status": "QUEUED_ON_CHANNEL", "channel_identity": { "channel": "WHATSAPP", "identity": "{{destination_phone_number}}", "app_id": "" }, "contact_id": "{{contact_id}}", "metadata": "", "processing_mode": "CONVERSATION" }, "message_metadata": "", "correlation_id": "", "channel_metadata": {} } ``` #### DELIVERED STATUS **LATAM** ``` { "total" : 1, "data" : [ { "id" : "c67f724a-2e70-4b43-b8e0-5b2f4862d427", "destination" : "{{destination_phone_number}}", "origin" : "{{business_phone_number}}", "sent" : true, "sentStatusCode" : 2, "sentStatus" : "SENT_SUCCESS", "sentDate" : "2024-04-02T17:20:19.389Z", "sentAt" : 1712078419389, "delivered" : true, "deliveredStatusCode" : 4, "deliveredStatus" : "DELIVERED_SUCCESS", "deliveredDate" : "2024-04-02T17:20:20.434Z", "deliveredAt" : 1712078420434, "read" : false, "updatedDate" : "2024-04-02T17:20:20.470Z", "updatedAt" : 1712078420470, "conversation" : { "id" : "66ce176488891b8c2cc263862faf014f", "origin" : { "type" : "SERVICE" }, "expiration" : null }, "type" : "MESSAGE" } ], "clientInfo" : { "customerId" : 42, "subAccountId" : 143 } } ``` **CONV API** ``` { "app_id": "{{app_id}}", "accepted_time": "2026-05-25T14:55:55.463Z", "event_time": "2026-05-25T14:55:58Z", "project_id": "{{project_id}}", "message_delivery_report": { "message_id": "01KSFT59J7XHRR59727FJC6MEJ", "conversation_id": "", "status": "DELIVERED", "channel_identity": { "channel": "WHATSAPP", "identity": "{{destination_phone_number}}", "app_id": "" }, "contact_id": "{{contact_id}}", "processing_mode": "DISPATCH" }, "message_metadata": "{\"pricing_category\":\"service\",\"whatsapp_conversation_id\":\"2066dee2ae4b3cc271b11d0e9c19f17d\",\"pricing_type\":\"free_customer_service\"}", "channel_metadata": { "whatsapp": { "conversation": { "type": "service" }, "sender_phone_number": "{{business_phone_number}}", "pricing": { "model": "PMP", "type": "free_customer_service", "category": "service" }, "user_profile": { "country_code": "BR", "phone_number": "{{destination_phone_number}}", "user_id": "{{destination_bsuid}}" } } } } ``` #### READ STATUS **LATAM** ``` { "total": 1, "data": [ { "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91", "correlationId": "...", "destination": "{{destination_phone_number}}", "origin": "{{business_phone_number}}", "campaignId": 100, "campaignAlias": "...", "flowId": "...", "extraInfo": "...", "sent": true, "sentStatusCode": 1, "sentStatus": "sent status", "sentDate": "2017-12-18T17:09:31.891Z", "sentAt": 1513616971891, "delivered": true, "deliveredStatusCode": 1, "deliveredStatus": "delivered status", "deliveredDate": "2017-12-18T17:09:31.891Z", "deliveredAt": 1513616971891, "read": true, "readDate": "2017-12-18T17:09:31.891Z", "readAt": 1513616971891, "updatedDate": "2017-12-18T17:09:31.891Z", "updatedAt": 1513616971891, "type": "MESSAGE", "conversation": { "id": "conversationId123", "origin": { "type": "REFERRAL_CONVERSION" }, "expiration": "2017-12-19T17:09:31.891Z" } } ], "clientInfo": { "customerId": 42, "subAccountId": 1291, "userId": 1 } } ``` **CONV API** ``` { "app_id": "01E8RCZPK7HFV70FFDWFFK0EXK", "accepted_time": "2020-06-22T11:05:53.910Z", "event_time": "2020-06-22T11:20:08.120Z", "project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61", "message_delivery_report": { "message_id": "01EBDV9EFP66ZA0GQJ9MCX1V9H", "conversation_id": "01EB199XQ2CBY50K6WZD9S1A22", "status": "READ", "channel_identity": { "channel": "WHATSAPP", "identity": "{{destination_phone_number}}", "app_id": "" }, "contact_id": "01EB197NDA4W7V15NPRCVV0S79", "metadata": "", "processing_mode": "CONVERSATION" }, "message_metadata": "{\"pricing_category\":\"service\",\"pricing_type\":\"regular\"}", "channel_metadata": { "whatsapp": { "conversation": { "type": "service" }, "sender_phone_number": "{{business_phone_number}}", "pricing": { "model": "PMP", "type": "free_customer_service", "category": "service" }, "user_profile": { "country_code": "BR", "phone_number": "{{destination_phone_number}}", "user_id": "{{destination_bsuid}}" } } } } ``` Check [WhatsApp Message Support | Conversation API | Sinch](https://developers.sinch.com/docs/conversation/channel-support/whatsapp/message-support#receiving-delivery-receipts) for more information ### MO Webhook Example Latam {% code lineNumbers="true" %} ``` { "total": 1, "data": [ { "id": "ce425ffe-bc62-421f-9261-e6819a5eab43", "source": "5519900000000", "origin": "5519900000000", "userProfile": { "name": "name of the user" }, "campaignId": 100, "correlationId": "...", "campaignAlias": "...", "flowId": "....", "extraInfo": "...", "message": { "type": "TEXT", "messageText": "Hi, this is a message from the user" }, "receivedAt": 1513616971473, "receivedDate": "2017-12-18T17:09:31.473Z" } ] } ``` {% endcode %} Conv API ``` { "app_id": "01E8RCZPK7HFV70FFDWFFK0EXK", "accepted_time": "2020-06-22T10:55:39.534687Z", "event_time": "2020-06-22T10:55:39.200Z", "project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61", "message": { "id": "01EBDTPPG3Q3EH14H7DY8X09MG", "direction": "TO_APP", "contact_message": { "text_message": { "text": "Hi from contact" } }, "channel_identity": { "channel": "WHATSAPP", "identity": "46712312312", "app_id": "" }, "conversation_id": "01EB199XQ2CBY50K6WZD9S1A22", "contact_id": "01EB197NDA4W7V15NPRCVV0S79", "metadata": "", "accept_time": "2020-06-22T10:55:39.521500Z" } } ``` Check [WhatsApp Message Support | Conversation API | Sinch](https://developers.sinch.com/docs/conversation/channel-support/whatsapp/message-support#receiving-messages) for more information. ## Managing Templates You can find the complete WhatsApp template documentation here: * [Template Messages | Conversation API | Sinch](https://developers.sinch.com/docs/conversation/channel-support/whatsapp/template-support) Templates can be created and managed either: * Directly through the Sinch Build Dashboard -](https://docs.chatlayer.ai/bot-answers/dialog-state/user-input-bot-dialog) # Publishing & platform URLs FAQ In one of our previous platform updates, we have released a new version of Chatlayer that makes handling the live and draft versions of your bot much easier. Older customers may still know [cms.staging.chatlayer.ai](http://cms.staging.chatlayer.ai/) instead of [app.chatlayer.ai](http://app.chatlayer.ai/). We’re introducing the [app.chatlayer.ai](http://app.chatlayer.ai/) URL that unifies everything that’s used to be on the [cms.staging.chatlayer.ai](http://cms.staging.chatlayer.ai/) and the [cms.chatlayer.ai](http://cms.chatlayer.ai/) URLs. ## Why are we changing this? We’ve received a few support tickets by customers accidentally making changes to their live bots when they wanted to do so in the staging environment. And we get it, it’s too easy to make mistakes in a URL! We also think it’s quite a hassle to remember which URL hosts which environment, especially if you’re a new Chatlayer user. ## So, what has changed? ### Chatlayer URL Instead of having a separate URL for Staging & Production, we now have 1 URL for everything: [app.chatlayer.ai](http://app.chatlayer.ai/). You can manage both the live & draft versions of your bot through this URL. Now when you open a bot on [app.chatlayer.ai](http://app.chatlayer.ai/), it will open the DRAFT version of that bot. Go to the 'publish' tab to, well, publish your bot. ### Publishing a bot We’ve renamed the “Versioning” tab to “Publish”. When you’re ready to publish a newer version of the bot, just click the “Publish” button and follow the steps in the platform. ### Editing your LIVE bot We recommend against changing the LIVE version of the bot directly. However, in some cases, if you need to make some quick changes without publishing an entirely new version, it can be useful. To change the LIVE version of the bot, go to the “Publish” page. On this page, look for the LIVE version of the bot on the right and click the “Open live mode” button.  ### Channels Your bot can still connect to draft and live channels separately, exactly like you’re doing now in the Staging and Production environments. However, we want to give a better overview, so we’re consolidating all your channels into one single table.  ### Conversations Only one small change on the conversations page: both LIVE and DRAFT conversations are now visible within the same table. You can filter in this table to show either one. ### Bot export When you export a bot, you can now choose between exporting the LIVE or DRAFT version of that bot. ## What is not changing? Your workflow will remain the same: you can publish a new version of the bot from draft to live whenever it’s ready. The Chatlayer API URLs will not change. ## FAQ * Am I losing my staging environment? No, the databases and infrastructure between the staging and production environments have been the same for over a year already. We are just merging the URLs. Your workflow remains the same: you can publish a new version from draft to live whenever it’s ready. * Will the old URLs (using ‘cms’) still work? The ‘cms’ URLs will continue to work for now. At some point in the future we will redirect them to [app.chatlayer.ai](http://app.chatlayer.ai/) URLs. There will be no change to the URLs that you use in your APIs. * What do I have to change to my account or bot? Nothing! Your workflow will remain the same: you can publish a new version of the bot from draft to live whenever it’s ready. The Chatlayer API URLs will not change. * Will there be any downtime of the bots during or after the release? We have been secretly preparing for this release for a long time, so in the background, everything has been merged already. This means that this change isn’t actually a really big one. Hence, we do not expect any downtime during or after the release of your bot. * What will happen to the analytics dashboard? If you have a live version of your bot, we will show you the stats from that live version. If you don’t, we will show some sample data in the analytics dashboard. * What should I do if I still have questions? If you have any questions about your bot specifically, feel free to [reach out to us](http://support.chatlayer.ai/). # Latam Messaging Technical Documentation regarding API & Integrations API & Integrations Welcome to our technical documentation for developers! Here you’ll find everything you need to integrate your business to our messaging platform. **API & Integrations Menu.** **API & Integrations** * ****[**Introduction – Types of Integration**](https://docs.wavy.global/documentacao-tecnica/todas-as-integracoes/introducao) * [**Atlas API**](https://docs.wavy.global/documentacao-tecnica/todas-as-integracoes/atlas-api)**** * ****[**SMS API**](https://docs.wavy.global/documentacao-tecnica/todas-as-integracoes/sms-api)**** * ****[**Email API**](https://docs.wavy.global/documentacao-tecnica/todas-as-integracoes/e-mail-api) * ****[**Fallback API**](https://docs.wavy.global/documentacao-tecnica/todas-as-integracoes/fallback-api) * ****[**WhatsApp API**](https://docs.wavy.global/documentacao-tecnica/todas-as-integracoes/whatsapp-api) * ****[**WhatsApp Groups API**](https://docs.wavy.global/documentacao-tecnica/todas-as-integracoes/grupos-de-whatsapp-api) * ****[**WhatsApp Lists via API**](https://docs.wavy.global/documentacao-tecnica/todas-as-integracoes/listas-whatsapp-via-api) * ****[**WhatsApp Messaging via FTP**](https://docs.wavy.global/documentacao-tecnica/todas-as-integracoes/envio-whatsapp-via-ftp) * ****[**Campaigns API**](https://docs.wavy.global/documentacao-tecnica/todas-as-integracoes/campanhas-api) * ****[**TTL - Time to Live**](https://docs.wavy.global/documentacao-tecnica/todas-as-integracoes/ttl-time-to-live) * ****[**Webhook**](https://docs.wavy.global/documentacao-tecnica/todas-as-integracoes/webhook%22%20/t%20%22_blank)**** # Introduction - Integrations Welcome to our documentation for developers Here you will find everything you need to integrate your company to our messaging platform. ### Types of Integration You can integrate through the following methods: | | | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **HTTPS API** | Allows you to send and receive messages and statuses through HTTPS protocol using the GET or POST methods | | **SMPP API** | Specific protocol for exchanging SMS messages; it allows you to maintain an active connection with our SMPP server and is suitable for customers whose traffic is over 5 million messages per month | | **SFTP API** | Protocol used to transfer files; it is suitable for mass messaging (bulk). The files are transferred by the customer to our servers and are immediately processed | | **Websphere MQ** | Used to transfer messages between Websphere MQ servers; it is suitable for customers whose traffic is over 30 million messages per month, especially financial banks where the customer already has this system in operation for internal messages. This integration option has an environment setup and maintenance fee, priced at R$50,000.00 and R$2,000.00 respectively | ### API & Integrations Menu. {% hint style="info" %} API & Integrations * [Introduction – Types of Integration ](https://doc-messaging.wavy.global/#introduction) * [SMS API](https://doc-messaging.wavy.global/#sms-api) * [WhatsApp API](https://doc-messaging.wavy.global/#whatsapp-api) * [WhatsApp Lists via API ](https://doc-messaging.wavy.global/#whatsapp-lists-via-api) * [WhatsApp Messaging via FTP](https://doc-messaging.wavy.global/#api-sftp-whatsapp) * [Campaigns API](https://doc-messaging.wavy.global/#campaigns-api) {% endhint %} # SMS API Technical Documentation: SMS API. ## Important Terms ### **Important Terms** | | | | | ------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **MT** | Mobile Terminated | Term used for messages that have the user (device) as destination. I.e., **messages originating from your company**, destined for the user (device) | | **MO** | Mobile Originated | Term used for messages that have your company as destination. I.e., **messages originating from the user** (device). It is used, for instance, in question and answer flows via SMS, when confirmation is required from the user. | | **Response** | Synchronous response from Wavy | The immediate response to a request made in our API, where we inform whether the message has been accepted by our platform. | | **Callback** | Sent status | The first sent status we return, where we inform whether the message has been delivered **to the carrier**. | | **LA** | Short Code | A short 5- or 6-digit number, used for sending and receiving SMS messages. They are appointed by carriers to approved integrators (Wavy) and have antifraud and antispam rules | | **DR or DLR** | Delivery Receipt |
The second sent status we return, where we inform whether the message was delivered to the device. The carriers send this information to Wavy, and we relay it to the customer. Delivery time varies: for example, if the device was turned off at the time the message was sent and the user turned it back on 2 hours later, this DLR status will be delivered to the customer with a 2-hour delay.
• This receipt of delivery to the device will only exist in cases where the message has been successfully delivered to the carrier, i.e., the first status (callback) was successful.
• It is very important to highlight that unfortunately carriers Oi and Sercomtel do not have this functionality, that is, they do not give us information on delivery to the device. Messages sent to numbers from those carriers will only have information on delivery to the carrier (callback)
| ## Message Flow Simplified Flow: MT, Callback, DLR, MO !\[Diagram Description automatically generated]\(/files/-MlGj-fPMNPcZsbwy1u5) ## HTTPS API This API allows you to automatize both single and bulk message requests and the retrieval of sent statuses through queries. It uses HTTP protocol with TLS and accepts the GET method with query string parameters and the POST method with [JSON](http://json.org/) parameters. ### Authentication To send messages and run queries in our API, you need to authenticate using a combination of either username or email and a token. | Field | Details | Data Type | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | **UserName** | Your username or email | String | | **AuthenticationToken** | Your authentication token. Check [here](https://messaging.movile.com/messaging/user/api_configuration) and read username descriptions below. | String | | Type | Details | | | **Administrator** | Admin user for your company; it is used for creating/editing/deactivating subaccounts and other users, and it can view reports of the entire company. This user does not send messages, whether through the portal or via API integration. | | | **User** | User used for sending messages via API and portal; it can view reports specific to its subaccount. A user is always related to a single subaccount. A subaccount can have multiple users. Each subaccount is a cost center in our platform; messages are broken down in reports and financially by subaccount, and not by user. | | | **templateID** | SMS template identifier. The text of the message will be retrieved and it should first be created through the Messaging Portal. | Long | | **templateName** | SMS template name. It may not be exclusive, resulting in an error if more than one template is found for the user’s access level. The text of the message will be retrieved and it should first be created through the Messaging Portal | String | ### Connection Details | | | | ------------------ | ------------------------------------------------------------ | | **Hostname** | api-messaging.wavy.global | | **APIs** | Single messages /v1/send-sms Bulk messages /v1/send-bulk-sms | | **Port** | 443 (https) | | **Protocol** | HTTPS (TLS encryption) | | **Authentication** | username + token | | **Portal** | messaging.wavy.global | ### Encoding The encoding standard used is UTF-8, all message contents must follow this standard. You can escape characters if you wish or encode using HTTP format. You can see some encoding examples to the side ***“messageText”:“A combinação foi perfeita :)”*** Or you can escape characters if you so wish: ***“messageText”:“A combina\u00e7\u00e3o foi perfeita :)”*** ****** ## Sending Messages (MT) ### Sending with GET Method - Individual curl -X POST \\Options:
text (default),
image,
audio,
document,
hsm,
video.
| ### **Element** | **Name** | | Required | | Description | | ----------- | - | -------- | - | ----------------------------------------- | | **url** | | Yes | | Media URL. Use only with HTTP/HTTPS URLs. | | **type** | | Yes | | Type of media (JPEG, MP3, PDF, etc.) | | **caption** | | Yes | | Name of media | ## **Webhooks** Webhooks (or callbacks) are HTTP call returns set by the user that are triggered by specific events. Whenever a trigger event occurs, Wavy’s API will collect the data and immediately send a notification (HTTP request) to the URL chosen by the customer updating the status of messages sent or letting you know when you receive a message. When your customer sends you a message, Wavy Messaging’s API will send a POST HTTP request notification to the **Webhook**’s URL with the details. It is important that your **Webhook** returns a 200 OK HTTPS response to notifications (within 200 ms or asynchronously). Otherwise, Wavy Messaging’s API will consider this notification to have failed and will try again after some delay. **Important: The URL where you will receive Webhooks must be set up by our support team.** ### **General Format of a Webhook** | **Name** | Object Content | | ------------ | ------------------------------ | | **messages** | Incoming message notifications | | **statuses** | Message status updates | ### Status | Status | Description | WhatsApp Equivalent for Mobile Devices | | ---------------------- | ------------------------------------- | -------------------------------------- | | **SENT\_SUCCESS** | Message received by WhatsApp’s server | One check mark | | **DELIVERED\_SUCCESS** | Message delivered to the recipient | Two check marks | | **READ\_SUCCESS** | Message read by the recipient | Two blue check marks | ### Errors | **HTTP Code** | **Description** | | ------------- | -------------------------------------------- | | **2xx** | **Success** | | **200** | **Success (OK)** | | **201** | **Successfully Created (For POST requests)** | | **302** | **Found** | | **4xx** | **Client Errors** | | **400** | **Bad Request** | | **401** | **Unauthorized** | | **403** | **Forbidden** | | **404** | **Not Found** | | **405** | **Method Not Allowed** | | **412** | **Precondition Failed** | | **420** | **Message is Rate Limited** | | **429** | **Too Many Requests** | | **5xx** | **Server Errors** | | **500** | **Internal Server Error** | | **504** | **Timeout** | ### Other Statuses | Sent Code | Delivery Code | Status | Meaning | | --------- | ------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 102 | | CARRIER COMMUNICATION ERROR | Error in uploading media to WhatsApp | | 103 | | REJECTED\_BY\_CARRIER | A databank error has occurred | | 2 | 101 | EXPIRED | Message expired | | 2 | 104 | NOT\_DELIVERED |Potential Causes:
Limit reached -too many attempts to send messages, or failure to send message because the destination phone number is part of an experiment, or the template structure does not exist, or failure to send message because the destination number is outside the 24h service window to receive messages freely, or an error occurred when uploading media (unknown error),
or failure to send message because your account is ineligible on Facebook Business Manager,
or there was a temporary upload failure. Please try again later.
| | 202 | | INVALID\_DESTINATION\_NUMBER | Invalid WhatsApp contact | | 204 | | DESTINATION\_BLOCKED\_BY\_OPTOUT | Destination blocked by Opt-Out | | 206 | | INVALID\_MESSAGE\_LENGTH | Message is too long | | 207 | | INVALID\_MESSAGE\_TEXT | Invalid parameter value | | 209 | | INVALID\_CONTENT | Invalid type of UNKNOWN message | | 210 | | INVALID\_SESSION | Session or service window is not open and no fallback Template is set up | | 311 | | INTERNAL\_ERROR | Unable to verify WhatsApp API contacts | ### **Messages (MO)** When a customer sends you a message, Wavy Messaging’s API will send a POST HTTP request to the **Webhook’s URL with the details**. It is important that your **Webhook** returns a 200 OK HTTPS response to notifications (within 200 ms or asynchronously). Otherwise, Wavy Messaging’s API will consider this notification to have failed and will try again after some delay. **Important: The URL where you will receive Webhooks must be set up by our support team.** ## Common HTTP Status Code Responses ### Successful Request Response (200) { "Id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5", "destination": \[{ "id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5", "correlationId": "MyCorrelationId", "destination": "5519900001111." }] } If your request is successfully run, a list of destinations with the generated uuids will be returned: ### Authentication Error Response (401) { "errorCode": 401, "errorMessage": "Authentication Error: No user was found with this combination of username and Authentication token." } If a problem occurs with authentication, the following message will be returned: ### Status Update Callback Example { "total": 1, "data": \[ { "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91", "correlationId": "...", "destination": "5519900000000", "origin": "5519900000000", "campaignId": 100, "campaignAlias": "...", "flowId": "...", "extraInfo": "...", "sent": true, "sentStatusCode": 1, "sentStatus": "sent status", "sentDate": "2017-12-18T17:09:31.891Z", "sentAt": 1513616971891, "delivered": true, "deliveredStatusCode": 1, "deliveredStatus": "delivered status", "deliveredDate": "2017-12-18T17:09:31.891Z", "deliveredAt": 1513616971891, "read": true, "readDate": "2017-12-18T17:09:31.891Z", "readAt": 1513616971891, "updatedDate": "2017-12-18T17:09:31.891Z", "updatedAt": 1513616971891 } ], "clientInfo": { "customerId": 42, "subAccountId": 1291, "userId": 1 } } For every status update of sent messages (receipt of delivery to the end user, message read, etc.), a callback/webhook is sent. Callbacks are sent in bulk. Important: The endpoint that the webhook will use to send statuses must be set up by our support and operations team. The return format will have the following description: | Field | Details | Type | | -------------- | -------------------------------- | ---------- | | **total** | Number of callbacks in the call. | String | | **data** | List of Callbacks. | Data\[] | | **clientInfo** | Client information. | ClientInfo | ### Data: | Field | Details | Type | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | **id** | Last message id. | String | | **correlationId** | Unique ID set by you to compare to the message status (Callback and DLR). This parameter is optional, and you can use the ID generated by Wavy Messaging to compare. | String | | **destination** | Phone number to which your message was sent (including country code). E.g.: 5511900000000. | String | | **origin** | Phone number that identifies the WhatsApp Account (including country code). E.g.: 5511900000000. | String | | **campaignId** | Previously set campaignID. | String | | **campaignAlias** | Previously set campaign alias. | String | | **extraInfo** | Extra information sent with the original message. | String | | **sent** | Indicates whether the message has been sent. | Boolean | | **sentStatusCode** | Status Code generated by Wavy Messaging for the message indicating its sent status. | Number | | **sentStatus** | Sent status description. | Boolean | | **sentDate** | Date the message was sent. Format: yyyy-MM-dd’T'HH:mm:ssZ. | String | | **sentAt** | Time the message was sent, using Unix\_time format | Number | | **delivered** | Indicates whether the message has been delivered to its destination. | Boolean | | **deliveredStatusCode** | Status Code generated by Wavy Messaging indicating whether the message has been delivered. | Number | | **deliveredStatus** | Delivered status description. | String | | **deliveredDate** | Date the message was delivered. Format: yyyy-MM-dd’T'HH:mm:ssZ | String | | **deliveredAt** | Time the message was delivered, using Unix\_time format | Number | | **read** | Indicates whether the message has been read by the recipient. | Boolean | | **readDate** | Date the message was read. Format: yyyy-MM-dd’T'HH:mm:ssZ | String | | **readAt** | Time the message was read, using Unix\_time format | String | | **updatedDate** | Date the message status was updated. Format: yyyy-MM-dd’T'HH:mm:ssZ | String | | **updatedAt** | Time the message status was updated, using Unix\_time format | String | ### ClientInfo | Field | Details | Type | | ---------------- | -------------------------- | ------ | | **customerId** | Customer identification. | Number | | **subAccountId** | Subaccount identification. | Number | | **userId** | User identification. | Number | ### Status Statuses that can be sent in the callback: | Status | Sent Code | Delivery Code | Meaning | | --------------------------------------- | --------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **CARRIER\_COMMUNICATION\_ERROR** | 102 | | Error in uploading media to WhatsApp. | | **REJECTED\_BY\_CARRIER** | 103 | | A databank error has occurred. | | **SENT\_SUCCESS** | 2 | | | | **EXPIRED** | 2 | 101 | Message expired. | | | | | Failure to send message because it is too old. | | **NOT\_DELIVERED** | 2 | 104 | Limit reached - too many attempts to send messages. | | | | | Failure to send message because this user’s phone number is part of an experiment. | | | | | Structure unavailable: Customer unable to display HSM. | | | | | Failure to send message because you are outside the support window for freely messaging this user. Please use a valid HSM notification or reconsider. | | | | | Error uploading media (unknown error). | | | | | Failure to send message because your account is ineligible. Please verify your WhatsApp Business account. | | | | | Temporary upload failure. Please try again later. | | **DELIVERED\_SUCCESS** | 2 | 4 | | | **READ\_SUCCESS** | 2 | 5 | | | **INVALID\_DESTINATION\_NUMBER** | 202 | | Invalid WhatsApp contact. | | **DESTINATION\_BLOCKED\_BY\_OPTOUT** | 204 | | Destination blocked by Opt-Out. | | **INVALID\_MESSAGE\_LENGTH** | 206 | | Message is too long. | | **INVALID\_MESSAGE\_TEXT** | 207 | | Invalid parameter value. | | **INVALID\_CONTENT** | 209 | | Invalid type of UNKNOWN message. | | **INVALID\_SESSION** | 210 | | Session is not open and no fallback HSM is set up. | | **DESTINATION\_BLOCKED\_BY\_OPTIN** | 211 | | | | **DESTINATION\_BLOCKED\_BY\_WHITELIST** | 212 | | | | **INTERNAL\_ERROR** | 311 | | Unable to verify WhatsApp API contacts. | ### MO (Messages Sent by the End User to the WhatsApp Account) Text message example: { "total": 1, "data": \[ { "id": "ce425ffe-bc62-421f-9261-e6819a5eab43", "source": "5519900000000", "origin": "5519900000000", "userProfile": { "name": "username" }, "campaignId": 100, "correlationId": "...", "campaignAlias": "...", "flowId": "....", "extraInfo": "...", "message": { "type": "TEXT", "messageText": "Hello, this is a user message." }, "receivedAt": 1513616971473, "receivedDate": "2017-12-18T17:09:31.473Z" } ] } Extra Info example: { "segmentation\_list":\[ { "id":26, "customerId":42, "subAccountId":0, "name":"Movile WhatsApp Segmentation List", "active":true }, { "id":27, "customerId":43, "subAccountId":0, "name":"Movile WhatsApp Segmentation List 2", "active":true } ] } Media message example { "total": 1, "data": \[ { "id": "ce425ffe-bc62-421f-9261-e6819a5eab43", "source": "5519900000000", "origin": "5519900000000", "userProfile": { "name": "username" }, "campaignId": 100, "correlationId": "...", "campaignAlias": "...", "flowId": "....", "extraInfo": "...", "message": { "type": "IMAGE", "mediaUrl": "https\://...", "mimeType": "image/jpg", "caption": "..." }, "receivedAt": 1513616971473, "receivedDate": "2017-12-18T17:09:31.473Z" } ] } Location message example: { "total": 1, "data": \[ { "id": "ce425ffe-bc62-421f-9261-e6819a5eab43", "source": "5519900000000", "origin": "5519900000000", "userProfile": { "name": "username" }, "campaignId": 100, "correlationId": "...", "campaignAlias": "...", "flowId": "....", "extraInfo": "...", "message": { "location": { "geoPoint": "-22.894180,-47.047960", "name": "Wavy", "address": "Av. Cel. Silva Telles" } }, "receivedAt": 1513616971473, "receivedDate": "2017-12-18T17:09:31.473Z" } ] } Contact message example: { "total": 1, "data": \[ { "id": "ce425ffe-bc62-421f-9261-e6819a5eab43", "source": "5519900000000", "origin": "5519900000000", "userProfile": { "name": "username" }, "campaignId": 100, "correlationId": "...", "campaignAlias": "...", "flowId": "....", "extraInfo": "...", "message": { "contacts":\[ { "addresses":\[ { "city":"Menlo Park", "country":"United States", "country\_code":"us", "state":"CA", "street":"1 Hacker Way", "type":"HOME", "zip":"94025" }, { "city":"Menlo Park", "country":"United States", "country\_code":"us", "state":"CA", "street":"200 Jefferson Dr", "type":"WORK", "zip":"94025" } ], "birthday":"2012-08-18", "emails":\[ { "email":"Template category type. Possible values are
ACCOUNT\_UPDATE, PAYMENT\_UPDATE, PERSONAL\_FINANCE\_UPDATE, SHIPPING\_UPDATE, RESERVATION\_UPDATE, ISSUE\_RESOLUTION, APPOINTMENT\_UPDATE, TRANSPORTATION\_UPDATE, TICKET\_UPDATE, ALERT\_UPDATE, AUTO\_REPLY
| String | | template\_type |Template type. Possible values are
header\_footer or body\_only
| String | | messages\[] | List containing information on each template translation. The size of this list is equivalent to the number of supported languages in languages | \[Object] | | messages\[].status |Template status. Possible values are:
in\_analysis, approved, disapproved, error
In order for a template to be approved, its content must follow Facebook’s guidelines.
| String | | messages\[].header\_type |Header type. Possible values are
video, location, text, document, image or none
| String | | messages\[].header | Text contained in the text header. Only used when header\_type = text | String | | messages\[].text | Text contained in the body | String | | messages\[].footer | Text contained in the footer | String | | messages\[].buttons\_type |Button type. Possible values are
quick\_reply or call\_to\_action
| String | | messages\[].placeholders | Description of placeholders present in the body text, represented as {{1}}, {{2}}, etc. in the text field | \[String] | | messages\[].buttons.payload |Button content in JSON format serialized as a string.
Quick reply buttons will be in {"payload": \[{"text": "button text"}]} format
Call-to-action buttons will be in
{"payload": \[{"url": "https:wavy.global/en", "text": "Access our website", "type": "url"}, {"text": "Call us", "type": "phone\_number", "country\_code": "55", "phone\_number": "11900000000"}]} format
| String | ## Message Template Examples Template with a text header, body and footer: Template with an image header, body and no footer: Template with 2 parameters: # WhatsApp Interactive API ## Interactive Messages To send interactive messages we will follow the standard of other types of messages that can be seen [here](https://docs.wavy.global/documentacao-tecnica/todas-as-integracoes/whatsapp-api#whatsapp-api). #### Message | Field | Required | Details | Type | | ----------- | -------- | --------------------------------------- | ------------------- | | interactive | Yes | Field used to send interactive messages | Interactive Message | #### Interactive Message | Field | Required | Details | Type | | ---------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------- | ----------------- | | messageInteractiveType | Yes | Type of interactive message. Available options: LIST and REPLY\_BUTTON | String | | header | No | Header content | Header | | body | Yes | Main text | Body | | footer | No | Footer content | Footer | | listAction | When the messageInteractiveType is LIST | Contains parameters of a list message | ListAction | | replyButtonAction | When the messageInteractiveType is REPLY\_BUTTON | Contains parameters of a reply button message | ReplyButtonAction | | alternativeText | No | Text that will be sent if the user’s mobile phone does not support interactive messages | String | #### Header If the message has a header, **exactly one of the fields below must be filled**. If the message type is LIST only the text field is accepted. | Field | Details | Type | | -------- | -------------------------------------------------------------------------- | -------- | | text | Header text. Maximum 60 characters. Allows the use of emojis and markdown. | String | | document | Complex Document object. | Document | | video | Complex Video object. | Video | | image | Complex Image object. | Image | | location | Complex Location object. | Location | **Image** | Field | Required | Details | Type | | ----- | -------- | ------------------------------------------------------------------------------------------------ | ------ | | type | Yes | Type/extension of the image that will be sent in the message. Available options: JPG, JPEG, PNG. | String | | url | Yes | URL of the content (image) that will be sent. | String | **Video** | Field | Required | Details | Type | | ----- | -------- | ------------------------------------------------------------------------------------- | ------ | | type | Yes | Type/extension of the video that will be sent in the message. Available options: MP4. | String | | url | Yes | URL of the content (video) that will be sent. | String | **Document** | Field | Required | Details | Type | | ----- | -------- | ---------------------------------------------------------------------------------------- | ------ | | type | Yes | Type/extension of the document that will be sent in the message. Available options: PDF. | String | | url | Yes | URL of the content (document) that will be sent. | String | **Location** | Field | Required | Details | Type | | -------- | -------- | --------------------------------------------- | ------ | | name | No | Location name. | String | | address | No | Location address. | String | | geoPoint | Yes | Coordinates in the format: latitude,longitude | String | #### Body/Footer | Field | Required | Details | Type | | ----- | -------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | | text | Yes | Cannot be an empty string. Allows for emojis and markdown. Body: Maximum 1024 characters. Footer: Maximum 60 characters. | String | #### ListAction | Field | Required | Details | Type | | -------- | -------- | ------------------------------------------------- | ---------- | | button | Yes | Content to be written inside the button. | String | | sections | Yes | List of sections. Must have at least one section. | Section\[] | **Section** | Field | Required | Details | Type | | ----- | -------- | ------------------------------------------------------------------------- | ------ | | rows | Yes | List rows. Must have at least one row and at most 10 adding all sections. | Row\[] | **Row** | Field | Required | Details | Type | | ----------- | -------- | --------------- | ------ | | identifier | Yes | Row identifier | String | | title | Yes | Row title | String | | description | No | Row description | String | #### ReplyButtonAction | Field | Required | Details | Type | | ------- | -------- | ---------------------------- | --------- | | buttons | Yes | List with 1, 2, or 3 Buttons | Button\[] | **Button** | Field | Required | Details | Type | | ----- | -------- | ---------------- | ----- | | reply | Yes | Button structure | Reply | **Reply** | Field | Required | Details | Type | | ------- | -------- | ------------------------------------------------------------------- | ------ | | title | Yes | Text to be written inside the button. Maximum 20 characters. | String | | payload | Yes | Information to be returned in the callback. Maximum 256 characters. | String | ### Request Examples **LIST** ``` { "destinations": [ { "correlationId": "MyCorrelationId", "destination": "5519900001111" } ], "message": { "interactive": { "messageInteractiveType": "LIST", "header": { "text": "Sample text" }, "body": { "text": "Main message text" }, "footer": { "text": "Footer text" }, "listAction": { "button": "button text", "sections": [ { "rows": [ { "identifier": "9ab8d65e-d389-4123-b97b-702e658cc9e4", "title": "August 7, 11:00", "description": "Saturday, August 7, 2021. 11:00AM" }, { "identifier": "2051afef-e000-47d0-99a5-7d96c17968b2", "title": "August 7, 15:00", "description": "Saturday, August 7, 2021. 3:00PM" }, { "identifier": "55baac93-a513-45d0-ad9e-2e2271861fc8", "title": "August 9, 11:00", "description": "Monday, August 9, 2021. 11:00AM" }, { "identifier": "e2703f03-689c-4d1e-b0e9-4045d6687605", "title": "August 9, 15:00", "description": "Monday, August 9, 2021. 4:00PM" } ] } ] }, "alternativeText": "Simple message text" } } } ``` **REPLY\_BUTTON** ``` { "destinations": [ { "correlationId": "MyCorrelationId", "destination": "5519900001111" } ], "message": { "interactive": { "messageInteractiveType": "REPLY_BUTTON", "header": { "text": "Sample text", "image": { "type": "JPG", "url": "http://...jpg" }, "video": { "type": "MP4", "url": "http://...mp4" }, "document": { "type": "PDF", "url": "http://...pdf" }, "location": { "geoPoint": "-22.894180,-47.047960", "name": "Wavy", "address": "Av. Cel. Silva Telles" } }, "body": { "text": "Main message text" }, "footer": { "text": "Footer text" }, "replyButtonAction": { "buttons": [ { "reply": { "title": "Display Text 1", "payload": "callback_payload_1" } }, { "reply": { "title": "Display Text 2", "payload": "callback_payload_2" } } ], }, "alternativeText": "Simple message text" } } } ``` ## Interactive Message Callback #### Callback | Field | Details | Type | | ---------- | -------------------------------------------------------- | ---------- | | total | Number of callbacks in this request | Long | | data | List of messages sent by the user | Data\[] | | clientInfo | Information of the client that is receiving the messages | ClientInfo | #### Data | Field | Details | Type | | ------------- | ------------------------------------------------------------------------------------------------- | ----------- | | id | Message identifier | String | | source | Phone number of who sent the message | String | | origin | Phone number of the WhatsApp Account that received the message | String | | userProfile | User profile who sent the message | UserProfile | | correlationId | Unique ID sent by the customer when sending the message to be returned in the callback. Optional. | String | | campaignId | Campaign related to the message | String | | campaignAlias | Alias of the campaign related to the message | String | | message | Message received | Message | | receivedDate | Date the message was received. Format: yyyy-MM-dd’T'HH:mm:ssZ | String | | receivedAt | Date the message was received, using Unix\_time format | Long | | extraInfo | Extra information related to the message. Format: Json | String | | session | Session information | Session | #### UserProfile | Field | Details | Type | | ---------- | ----------------- | ------ | | name | WhatsApp username | String | | whatsAppId | User phone number | String | #### Session | Field | Details | Type | | --------- | ---------------------------------- | ------ | | sessionId | Id of this user’s session | String | | createdAt | Creation timestamp of this session | Long | #### Message | Field | Details | Type | | --------------- | ------------------------------------------------------------------------------------------------------- | ------------------- | | type | Type of message sent by the user: TEXT - IMAGE - AUDIO - DOCUMENT - STICKER - BUTTON - ORDER | String | | **messageText** | Text of the message sent by the user. For list replies, it is the same as the rowTitle the user clicked | String | | mediaUrl | Url to download media sent by the user | String | | mimeType | Mime type of the file sent by the user | String | | caption | Label of media sent by the user | String | | location | Location sent by the user | Location | | contacts | List of contacts sent by the user | Contact\[] | | interactive | Fields related to interactive messages | ReceivedInteractive | #### ReceivedInteractive | Field | Details | Type | | ----------- | ----------------------------------------------------------------- | ----------- | | type | Type of interactive message. Can be: LIST\_REPLY or BUTTON\_REPLY | String | | listReply | List reply (LIST) | ListReply | | buttonReply | Button reply (REPLY\_BUTTON) | ButtonReply | **ListReply** | Field | Details | Type | | ------------- | --------------------------------------- | ------ | | rowIdentifier | Identifier of the row the user selected | String | | rowTitle | Title of the row the user selected | String | **ButtonReply** | Field | Details | Type | | ------- | ------------------------------------------- | ------ | | payload | Text set at the time of sending the message | String | | title | Title of the button the user clicked | String | #### ClientInfo | Field | Details | Type | | ------------ | ----------------------------------------------------- | ---- | | customerId | customerId of the customer who receives the message | Long | | subAccountId | subAccountId of the customer who receives the message | Long | | userId | userId of the customer who receives the message | Long | # WhatsApp Lists via API Technical Documentation: WhatsApp Lists via API ### **Consulting Lists via API** **OPT IN/OUT & BLACK/WHITE LIST** **API - Possible list request types:** * OPT IN * OPT OUT * BLACK LIST * WHITE LIST * OPEN SESSIONS **Request** You need to make a GET request to the URL ***| Field | Description |
|---|---|
| SMPP | Specific protocol made to exchange SMS messages, it permits a active connection with the SMPP servers, it is recommended to the clients that have 5 millions or more messages per month The instability in this component affects in general form the sending and receiving of messages trough your API SMPP. |
| Web service API | This API permits that you automatize the sending messages requisitions, unique or in lot, and the recovery of the sending status trough consultations. She utilizes the HTTP protocol with TLS and accepts the GET methods, with the passage of parameters in the query string or POST with parameters in JSON The instability in this service affects in general form the sending and receiving of SMS trought the API. |
| Web Interface | This component refers at your platform Messaging. The instability in this service can affects the sending and receiving of SMS and Whatsapp messages trough our platform. |
| Webhook DLR (delivery to handset) | The instability in this component directly affects the delivery to handset status in your Webhook. |
| SMPP DLR (delivery to handset) | The instability in this component directly affects the delivery to handset status in your API SMPP. |
| SMPP Callback (delivery to carrier) | The instability in this component directly affects the delivery to carrier status in your Webhook. |
| Webhook Callback (delivery to carrier) | The instability in this component directly affects the delivery to handset status in your API SMPP. |
| Carrier | The instability in the carrier is linked whit the service outage provided by the carrier, when this happens we can expect delays on the sending and in the receiving of messages, we inform the carrier about the delay and we stabilize our messages rows in our side, this instability and your resolution time can vary from carrier to carrier. |
| Internal Queues MT | The instability in this integration is linked directly with the sending of messages trough Whatsapp, when this happens, we can expect delays in the delivery of that message, until the message row is gradually emptied. |
| Internal Queues (MO) | The instability in this integration is linked directly with the receiving of messages trough Whatsapp, when this happens, we can expect delays in the receiving of that message, until the message row is gradually emptied. |