> For the complete documentation index, see [llms.txt](https://docs-latam.messaging.sinch.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-latam.messaging.sinch.com/whatsapp/conversation-api-migration-guide.md). # Conversation API migration guide ## Onboarding ### Migrating Active Numbers If you are currently using Sinch LATAM WhatsApp API and desire to migrate to Sinch Conversation API + WhatsApp service, please contact your Account Manager and request the migration. After the migration request is submitted, we will schedule the migration date. On the scheduled day, our team will handle the migration process automatically for you, which means that your active numbers will stop working on the Latam platform and start working exclusively on the Conversation API. It is very important that you prepare your backend and integration with us accordingly, and verify that everything is working as expected during and after the migration process. ### Starting from Scratch If you do not have any active numbers in Latam and want to start using the Native Conversation API from scratch, simply follow the official setup guide below: * [WhatsApp Set Up | Conversation API | Sinch](https://developers.sinch.com/docs/conversation/channel-support/whatsapp/set-up) ## Sending Your First Message Now that you have completed the onboarding process, you can send your first message. If you don’t want to add or migrate your own phone number to test Conversation API Platform, you can contact your Account Manager and he will provide a demo test number for you, following these steps: 1. You may create a new subproject in your Sinch Build Configuration, let’s say `ConvAPI Integration Check`. Ask your account manager to help you create a subproject. 2. Contact your account manager and ask them to get a Sinch demo number and have it assigned to `ConvAPI Integration Check` subproject. You’ll have a maximum of 30 days to use this demo number for testing / validation purposes. 3. Create a new ConvAPI App under `ConvAPI Integration Check` subproject and assign this WA demo number to it. 4. Do full WA testing using your backend systems and make sure that both outbound and inbound traffic is working fully as expected. To send your first message of the WA testing, you can use one of these two ways: 1. Using Sinch Build Test Tool ([https://dashboard.sinch.com/convapi/apps/{your-app}/test-message](https://dashboard.sinch.com/convapi/apps/%7Byour-app%7D/test-message)) 2. Directly Through Conversation API ### Option 1 - Sinch Build Test Tool After creating an app and having a number associated with it, you may go to your App Sinch Build Page - [https://dashboard.sinch.com/convapi/apps/](https://dashboard.sinch.com/convapi/apps/%7Byour-app%7D), select your app, and click `Send Test Messages` under the **Test your setup** section. This is an easier way to test your environment, since we prepare the payload, authentication and URL automatically for you, so that you can send the request with one click, but it’s also a limited environment, since we will not route incoming webhooks to your URL in the test mode. ### Option 2 - Directly Through Conversation API 1. Since we’re using a simple non-template payload for this example, you must first send a message from the *destination\_phone\_number* to the business, opening the WhatsApp [Customer Service Window](https://community.sinch.com/t5/WhatsApp/What-is-a-Customer-Care-Session/ta-p/6858). If you don’t want to do that, you can use a template message and skip this step. 2. Use your *key\_id* and *key\_secret* to complete [WhatsApp Migration guide from Latam to Native ConvAPI | Native Conversation API Authentication](#native-conversation-api-authentication) and add the Authentication Header to your request. 3. Send a [WhatsApp Migration guide from Latam to Native ConvAPI | Simple Text Payload](#sending-a-simple-text-payload). #### Native Conversation API Authentication All authentication information needed is described in [Authentication](https://developers.sinch.com/docs/conversation/api-reference/conversation/section/overview/authentication). You can test sending messages with Basic Auth using your *key\_id* and *key\_secret*, but OAuth Token is highly recommended. #### Sending a Simple Text Payload The endpoint used to send messages depends on your environment, and can be one of the following: | Conversation API (US Production) | `https://us.conversation.api.sinch.com/v1/projects/{project_id}/messages:send` | | -------------------------------- | ------------------------------------------------------------------------------ | | Conversation API (EU Production) | `https://eu.conversation.api.sinch.com/v1/projects/{project_id}/messages:send` | | Conversation API (BR Production) | `https://br.conversation.api.sinch.com/v1/projects/{project_id}/messages:send` | Check the [Overview](https://developers.sinch.com/docs/conversation/api-reference/conversation/section/overview) for a complete Postman Collection and our API documentation. In this example, send the following payload to your Conversation API endpoint: ``` { "app_id": "{{conv_api_app}}", "recipient": { "identified_by": { "channel_identities": [ { "channel": "WHATSAPP", "identity": "{{destination_phone_number}}" } ] } }, "message": { "text_message": { "text": "Hello from Sinch Conversation API" } } } ``` If you’ve completed the three steps, you should receive the message on your *destination\_phone\_number*. ## Request Fields ### Root payload | **LATAM field** | **Sinch Conv API field** | **Notes** | | ------------------ | -------------------------------- | ------------------------------------------------------------------------------------- | | `destinations` | `recipient` | Destination list; each item becomes one message per recipient in Conv API. | | `message` | `message` | Message payload content. | | `flowId` | `message_metadata.flowId` | No dedicated field. You can set it in messageMetadata to receive it back in webhooks. | | `defaultExtraInfo` | `message_metadata.extraInfo` | No dedicated field. You can set it in messageMetadata to receive it back in webhooks. | | `campaignAlias` | `message_metadata.campaignAlias` | No dedicated field. You can set it in messageMetadata to receive it back in webhooks. | | `partnerId` | `message_metadata.partnerId` | No dedicated field. You can set it in messageMetadata to receive it back in webhooks. | ### Destination | **LATAM Destination field** | **Sinch Conv API field** | **Notes** | | --------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `correlationId` | `correlation_id` | Per-recipient correlation. | | `destination` | `recipient.identified_by.channel_identities[0].identity` | Recipient WhatsApp number/identity. | | `extraInfo` | `message_metadata.extraInfo` | No dedicated field. You can set it in messageMetadata to receive it back in webhooks. | ### Message | **LATAM Message field** | **Sinch Conv API field** | **Notes** | | ----------------------- | ----------------------------------------- | --------------------------------------------------------- | | `messageText` | `message.text_message.text` | Text message. | | `image` | `message.media_message` | Image media payload. | | `audio` | `message.media_message` | Audio media payload. | | `document` | `message.media_message` | Document media payload. | | `location` | `message.location_message` | Location payload. | | `contacts` | `message.contact_info_message` | Contact payload (Conv processes one contact per message). | | interactive | depends on `interactiveMessageType` | Interactive Payload. | | template | `message.template_message` | Template Payload. | | `previewFirstUrl` | `channel_properties.WHATSAPP_PREVIEW_URL` | First URL preview control. | *** ## Latam VS Conv API Requests ### Text
#### Text Object | **LATAM Text field** | **Sinch Conv API field** | | -------------------- | ----------------------------------------- | | `messageText` | `message.text_message.text` | | showFirstPreviewUrl | `channel_properties.WHATSAPP_PREVIEW_URL` | Latam Payload ``` { "destinations": [ { "destination": "{{destination_phone_number}}" } ], "message": { "messageText": "Hello from Sinch. https://www.sinch.com", "showFirstPreviewUrl": true } } ``` Conv API Payload ``` { "app_id": "{{conv_api_app}}", "recipient": { "identified_by": { "channel_identities": [ { "channel": "WHATSAPP", "identity": "{{destination_phone_number}}" } ] } }, "message": { "text_message": { "text": "Hello from Sinch. https://www.sinch.com" } }, "channel_properties": { "WHATSAPP_PREVIEW_URL": "true" } } ``` ### Image
#### Image Object | **LATAM Image field** | **Sinch Conv API field** | **Notes** | | --------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `type` | `-` | No need to specify type. | | `caption` | `message.card_message.description` | To use media with a caption ([check example](#image-with-caption)), you need to use Sinch’s card message. | | `url` | `message.media_message.url` or `message.card_message.media_message.url` | Media URL. | | `data` | `-` | Conv API does not allow base64 media content. | Latam Payload ``` { "destinations": [ { "destination": "{{destination_phone_number}}" } ], "message": { "image": { "type": "PNG", "url": "https://image-example.png" } } } ``` Conv API Payload ``` { "app_id": "{{conv_api_app}}", "recipient": { "identified_by": { "channel_identities": [ { "channel": "WHATSAPP", "identity": "{{destination_phone_number}}" } ] } }, "message": { "media_message": { "url": "https://image-example.png" } } } ``` ### Image With Caption
#### Image Object | **LATAM Image field** | **Sinch Conv API field** | **Notes** | | --------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `type` | `-` | No need to specify type. | | `caption` | `message.card_message.description` | To use media with a caption ([check example](#image-with-caption)), you need to use Sinch’s card message. | | `url` | `message.card_message.media_message.url` | Media URL. | | `data` | `-` | Conv API does not allow base64 media content. | Latam Payload ``` { "destinations": [ { "destination": "{{destination_phone_number}}" } ], "message": { "image": { "type": "JPEG", "url": "https://image-example.jpeg", "caption": "Image description" } } } ``` Conv API Payload ``` { "app_id": "{{conv_api_app}}", "recipient": { "identified_by": { "channel_identities": [ { "channel": "WHATSAPP", "identity": "{{destination_phone_number}}" } ] } }, "message": { "card_message": { "title": "Image title", "description": "Image description", "media_message": { "url": "https://image-example.jpeg" } } } } ``` ### Audio
#### Audio Object | **LATAM Audio field** | **Sinch Conv API field** | **Notes** | | --------------------- | --------------------------- | --------------------------------------------- | | `type` | `-` | No need to specify type. | | `url` | `message.media_message.url` | Media URL. | | `data` | `-` | Conv API does not allow base64 media content. | Latam Payload ``` { "destinations":[ { "destination":"{{destination_phone_number}}" } ], "message":{ "audio":{ "type":"MP3", "url":"https://...audio.mp3" } } } ``` Conv API Payload ``` { "app_id": "{{conv_api_app}}", "recipient": { "identified_by": { "channel_identities": [ { "channel": "WHATSAPP", "identity": "{{destination_phone_number}}" } ] } }, "message": { "media_message": { "url": "https://...audio.mp3" } } } ``` ### Document
#### Document Object | **LATAM Document field** | **Sinch Conv API field** | **Notes** | | ------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | `type` | `-` | No need to specify type. | | `caption` | `message.card_message.description` | To use media with a caption, you need to use Sinch’s card message. | | `url` | `message.media_message.url` or `message.card_message.media_message.url` | Document URL. | | `data` | `-` | Conv API does not allow base64 media content. | | `filename` | `message.media_message.filename_override` or `message.card_message.media_message.filename_override` | Document Name. | Latam Payload ``` { "destinations": [ { "destination": "{{destination_phone_number}}" } ], "message": { "document": { "type": "PDF", "url": "https://...document.pdf" } } } ``` Conv API Payload ``` { "app_id": "{{conv_api_app}}", "recipient": { "identified_by": { "channel_identities": [ { "channel": "WHATSAPP", "identity": "{{destination_phone_number}}" } ] } }, "message": { "media_message": { "url": "https://...document.pdf" } } } ``` ### Contact
#### Contact Object | **LATAM Contact field** | **Sinch Conv API field** | | ----------------------- | --------------------------------------------- | | `addresses` | `message.contact_info_message.addresses` | | `birthday` | `message.contact_info_message.birthday` | | `emails` | `message.contact_info_message.emailAddresses` | | `name` | `message.contact_info_message.name` | | `org` | `message.contact_info_message.organization` | | `phones` | `message.contact_info_message.phoneNumbers` | | `urls` | `message.contact_info_message.urls` | #### Contact’s Address | **LATAM Contact** **Address field** | **Sinch Conv API field** | | ----------------------------------- | ------------------------------------------------------- | | `street` | `message.contact_info_message.addresses[*].street` | | `city` | `message.contact_info_message.addresses[*].city` | | `state` | `message.contact_info_message.addresses[*].state` | | `zip` | `message.contact_info_message.addresses[*].zip` | | `country` | `message.contact_info_message.addresses[*].country` | | `country_code` | `message.contact_info_message.addresses[*].countryCode` | | `type` | `message.contact_info_message.addresses[*].type` | #### Contact’s Email | **LATAM Contact** **Email field** | **Sinch Conv API field** | | --------------------------------- | -------------------------------------------------------------- | | `email` | `message.contact_info_message.email_addresses[*].emailAddress` | | `type` | `message.contact_info_message.email_addresses[*].type` | #### Contact’s Name | **LATAM Contact** **Name field** | **Sinch Conv API field** | | -------------------------------- | ----------------------------------------------- | | `first_name` | `message.contact_info_message.name.first_name` | | `last_name` | `message.contact_info_message.name.last_name` | | `middle_name` | `message.contact_info_message.name.middle_name` | | `name_suffix` | `message.contact_info_message.name.suffix` | | `name_prefix` | `message.contact_info_message.name.prefix` | | `formatted_name` | `message.contact_info_message.name.full_name` | #### Contact’s Org | **LATAM Contact** **Org field** | **Sinch Conv API field** | | ------------------------------- | ------------------------------------------------------ | | `company` | `message.contact_info_message.organization.company` | | `department` | `message.contact_info_message.organization.department` | | `title` | `message.contact_info_message.organization.title` | #### Contact’s Phone | **LATAM Contact** **Phone field** | **Sinch Conv API field** | **Notes** | | --------------------------------- | ------------------------------------------------------------ | -------------------------------------- | | `phone` | `message.contact_info_message.phone_numbers[*].phone_number` | Phone number. | | `type` | `message.contact_info_message.phone_numbers[*].type` | Phone type. | | `wa_id` | No dedicated direct field | Usually treated as auxiliary metadata. | #### Contact’s Url | **LATAM Contact** **Url field** | **Sinch Conv API field** | **Notes** | | ------------------------------- | ------------------------------------------- | --------- | | `url` | `message.contact_info_message.urls[*].url` | URL. | | `type` | `message.contact_info_message.urls[*].type` | URL type. | *** Latam Payload ``` { "destinations": [ { "destination": "{{destination_phone_number}}" } ], "message": { "contacts": [ { "name": { "first_name": "Sinch", "formatted_name": "Sinch AB Full Name", "last_name": "AB" }, "addresses": [ { "street": "Av. Brig. Faria Lima", "city": "São Paulo", "state": "São Paulo", "zip": "01452-001", "country": "Brazil", "type": "WORK" } ] } ] } } ``` Conv API Payload ``` { "app_id": "{{conv_api_app}}", "recipient": { "identified_by": { "channel_identities": [ { "channel": "WHATSAPP", "identity": "{{destination_phone_number}}" } ] } }, "message": { "contact_info_message": { "name": { "first_name": "Sinch", "last_name": "AB", "full_name": "Sinch AB Full Name" }, "addresses": [{ "city": "São Paulo", "country": "Brazil", "state": "São Paulo", "street": "Av. Brig. Faria Lima", "zip": "01452-001", "type": "WORK" }] } } } ``` ### Location
#### Location Object | **LATAM Location field** | **Sinch Conv API field** | **Notes** | | ------------------------ | -------------------------------------- | ----------- | | `geopoint` | `message.location_message.coordinates` | Geopoint. | | `address` | `message.location_message.label` | Address | | `name` | `message.location_message.title` | Name/Title. | Latam Payload ``` { "destinations": [ { "destination": "{{destination_phone_number}}" } ], "message": { "location": { "geoPoint": "55.610479,13.002873", "address": "Meet your driver at the specified address.", "name": "Your ride is here!" } } } ``` Conv API Payload ``` { "app_id": "{{conv_api_app}}", "recipient": { "identified_by": { "channel_identities": [ { "channel": "WHATSAPP", "identity": "{{destination_phone_number}}" } ] } }, "message": { "location_message": { "title": "Your ride is here!", "label": "Meet your driver at the specified address.", "coordinates": { "latitude": 55.610479, "longitude": 13.002873 } } } } ``` ### Interactive #### Interactive Object | **LATAM Interactive Type** | **Sinch Conv API field** | **Notes** | | ----------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | `interactive` | `message` interactive output (varies by `messageInteractiveType`) | Interactive object. | | `messageInteractiveType = "LIST"` | `message.list_message` | List action mapped to `list_message`. | | `messageInteractiveType = "REPLY_BUTTON"` | `message.card_message` | Reply buttons mapped to card choices. | | `messageInteractiveType = "PRODUCT_LIST"` | `message.list_message` | Product list mapped to `ListMessage` with `ProductItem`. | | `messageInteractiveType = "CTA_URL"` | `message.choice_message` or `message.card_message` | Uses `cardMessage` only when header has media (`IMAGE`, `VIDEO`, `DOCUMENT`). | | `messageInteractiveType = "EXTENSION"` | `message.channel_specific_message.WHATSAPP` (`message_type = "FLOWS"`) | Flow payload serialized as channel-specific message. | | `messageInteractiveType = "ORDER"` | `message..channel_specific_message.WHATSAPP` (`messageType = "order_details"`) | Order payload serialized as channel-specific message. | #### Body, Header, Footer (Common Interactive Fields) | **Latam Interactive field** | **Sinch Conv API field** | **Notes** | | --------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `interactive.body.text` | `message.list_message.title` | For `list` and `product_list`. | | `interactive.body.text` | `message.card_message.title` | For `reply_button` and CTA with media header. | | `interactive.body.text` | `message.choice_message.text_message.text` | For CTA without media header. | | `interactive.body.text` | `message.channel_specific_message.WHATSAPP.body.text` | For `extension` and `order`. | | `interactive.footer.text` | `message.list_message.description` | For `list`; for `product_list` depends on multi/single product rule. | | `interactive.footer.text` | `message.card_message.description` | For `reply_button` and CTA with media header; for `product_list` depends on multi/single product rule. | | `interactive.footer.text` | `message.choice_message.message_properties.whatsapp_footer` | For CTA without media header. | | `interactive.footer.text` | `message.channel_specific_message.WHATSAPP.footer.text` | For `extension` and `order`. | | `interactive.header.text` | `message.list_message.message_properties.whatsapp_header` | For `list`. | | `interactive.header.text` | `message.card_message.message_properties.whatsapp_header` | For `reply_button`. | | `interactive.header.image.url / video.url / document.url` | `message.card_message.media_message.url` | For `reply_button` and CTA with media header. | | `interactive.header..caption` | `message.card_message.media_message.filename_override` | Caption is mapped as filename override. | | `interactive.header.*` | `message.channel_specific_message.header` | For `extension` and `order`, mapped as structured header (`text`, `image`, `video`, `document`). | #### Interactive List
**Interactive** | **LATAM Interactive Type** | **Sinch Conv API field** | | --------------------------------- | ----------------------------------------------------------------- | | `interactive` | `message` interactive output (varies by `messageInteractiveType`) | | `messageInteractiveType = "LIST"` | `message.list_message` | **Interactive’s ListAction** | **LATAM Interactive List Action field** | **Sinch Conv API field** | **Notes** | | --------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------- | | `interactive.listAction.button` | `message.list_message.message_properties.menu` | Stored as message property, not a dedicated top-level list field. | | `interactive.listAction.sections[*]` | `message.list_message.sections[*]` | Section array. | **Interactive’s ListSection** | **LATAM Interactive List Action Sections Field** | **Sinch Conv API field** | **Notes** | | ------------------------------------------------ | ------------------------------------------- | ------------------------------------- | | `interactive.listAction.sections[*].title` | `message.list_message.sections[*].title` | Optional section title. | | `interactive.listAction.sections[*].rows[*]` | `message.list_message.sections[*].items[*]` | Rows become list items with `choice`. | **Interactive’s ListRow** | **LATAM Interactive List Row Field** | **Sinch Conv API field** | **Notes** | | -------------------------------------------------------- | ---------------------------------------------------------------- | --------- | | `interactive.listAction.sections[*].rows[*].title` | `message.list_message.sections[*].items[*].choice.title` | Required. | | `interactive.listAction.sections[*].rows[*].identifier` | `message.list_message.sections[*].items[*].choice.postback_data` | Required. | | `interactive.listAction.sections[*].rows[*].description` | `message.list_message.sections[*].items[*].choice.description` | Optional. | Latam Payload ``` { "destinations": [ { "destination": "{{destination_phone_number}}" } ], "message": { "interactive": { "messageInteractiveType": "LIST", "header": { "text": "<>" }, "body": { "text": "title" }, "footer": { "text": "description" }, "listAction": { "button": "menu", "sections": [ { "title": "section 1", "rows": [ { "title": "row 1", "description": "description row 1", "identifier": "postback" } ] } ] } } } } ``` Conv API Payload ``` { "app_id": "{{conv_api_app}}", "recipient": { "identified_by": { "channel_identities": [ { "channel": "WHATSAPP", "identity": "{{destination_phone_number}}" } ] } }, "message": { "list_message": { "title": "title", "description": "description", "sections": [ { "title": "section 1", "items": [ { "choice": { "title": "row 1", "description": "description row 1", "postback_data": "postback" } } ] } ], "message_properties": { "menu": "menu text" } } } } ``` #### Interactive Product List
Fields Comparison **Interactive** | **LATAM Interactive Type** | **Sinch Conv API field** | | ----------------------------------------- | ----------------------------------------------------------------- | | `interactive` | `message` interactive output (varies by `messageInteractiveType`) | | `messageInteractiveType = "PRODUCT_LIST"` | `message.list_message` | **Interactive’s ProductListAction** | **Latam Interactive Product List field** | **Sinch Conv API field** | **Notes** | | ------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------ | | `interactive.productListAction.catalogId` | `message.list_message.message_properties.catalog_id` | Required. | | `interactive.productListAction.sections[*]` | `message.list_message.sections[*]` | Multi-product path. | | `interactive.productListAction.productRetailerId` | `message.list_message.sections[0].items[0].product.id` | Single-product fallback when `sections` is null. | | *(not in Latam)* | `message.list_message.sections[*].items[*].product.marketplace` | Marketplace. | **Interactive’s ProductListSection** | **Latam Interactive Product List Section field** | **Sinch Conv API field** | **Notes** | | ----------------------------------------------------------- | ------------------------------------------- | -------------- | | `interactive.productListAction.sections[*].title` | `message.list_message.sections[*].title` | Optional. | | `interactive.productListAction.sections[*].productItems[*]` | `message.list_message.sections[*].items[*]` | Product array. | **Interactive’s ProductListItem** | **Latam Interactive Product List Item field** | **Sinch Conv API field** | **Notes** | | ----------------------------------------------------------------------------- | ------------------------------------------------------ | --------- | | `interactive.productListAction.sections[*].productItems[*].productRetailerId` | `message.list_message.sections[*].items[*].product.id` | Required. | **multi/single product rule** | **Condition** | **Sinch Conv API field** | **Latam Field** | | ---------------------------------------------------------- | ---------------------------------- | -------------------------- | | Multi Product List (more than one product across sections) | `message.list_message.description` | `interactive.header.text` | | Single Product List | `message.list_message.description` | `interactive.footer.text`. | Latam Payload ``` { "destinations": [ { "destination": "{{destination_phone_number}}" } ], "message": { "interactive": { "messageInteractiveType": "PRODUCT_LIST", "header": { "text": "Title" }, "body": { "text": "Description" }, "footer": { "text": "Footer text" }, "productListAction": { "catalogId": "{{catalogId}}", "sections": [ { "title": "Section Title", "productItems": [ { "productRetailerId": "{{productId1}}" }, { "productRetailerId": "{{productId2}}" } ] } ] } } } } ``` Conv API Payload ``` { "app_id": "{{conv_api_app}}", "recipient": { "identified_by": { "channel_identities": [ { "channel": "WHATSAPP", "identity": "{{destination_phone_number}}" } ] } }, "message": { "list_message": { "title": "Title", "description": "Description", "sections": [ { "title": "Section Title", "items": [ { "product": { "id": "{{productId1}}", "marketplace": "BRIDGE" } }, { "product": { "id": "{{productId2}}", "marketplace": "BRIDGE" } } ] } ], "message_properties": { "catalog_id": "{{catalogId}}" } } } } ``` #### Interactive Reply Button
**Interactive** | **LATAM Interactive Type** | **Sinch Conv API field** | | ----------------------------------------- | ----------------------------------------------------------------- | | `interactive` | `message` interactive output (varies by `messageInteractiveType`) | | `messageInteractiveType = "REPLY_BUTTON"` | `message.choice_message` | **Interactive’s ReplyButtonAction** | **Latam Interactive Reply Button Action field** | **Sinch Conv API field** | **Notes** | | -------------------------------------------------------- | ----------------------------------------------------- | --------------- | | `interactive.replyButtonAction.buttons[*].reply.title` | `message.choice_message.choices[*].text_message.text` | Button Title. | | `interactive.replyButtonAction.buttons[*].reply.payload` | `message.choice_message.choices[*].postback_data` | Button Payload. | Latam Payload ``` { "destinations": [ { "destination": "{{destination_phone_number}}" } ], "message": { "interactive": { "messageInteractiveType": "REPLY_BUTTON", "header": { "text": "Sample text" }, "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" } }, { "reply": { "title": "Display Text 3", "payload": "callback_payload_3" } } ] } } } } ``` Conv API Payload ``` { "app_id": "{{conv_api_app}}", "recipient": { "identified_by": { "channel_identities": [ { "channel": "WHATSAPP", "identity": "{{destination_phone_number}}" } ] } }, "message": { "choice_message": { "text_message": { "text": "title" }, "choices": [ { "text_message": { "text": "option 1" }, "postback_data": "option1" }, { "text_message": { "text": "option 2" }, "postback_data": "option2" }, { "text_message": { "text": "option 3" }, "postback_data": "option3" } ] } } } ``` ### Template #### 1) Template (base structure) | **Latam Template field** | **Sinch Conv API field** | **Notes** | | ------------------------ | ------------------------------------------------------------------ | ---------------------------------- | | `template` | `message.template_message` | Output type is `template_message`. | | `template.elementName` | `message.template_message.channel_template.WHATSAPP.template_id` | Required . | | `template.languageCode` | `message.template_message.channel_template.WHATSAPP.language_code` | Required . | | `template.*params` | `message.template_message.channel_template.WHATSAPP.parameters` | Template parameters. | *** #### 2) Body parameters Body parameters are indexed from 1 in Sinch’s parameters (`body[1]`, `body[2]`, ...). | **Latam Template field** | **Sinch Conv API field** | **Notes** | | -------------------------------- | --------------------------------- | -------------------------------------------------- | | `template.bodyParameters[index]` | `parameters["body[index+1]text"]` | 1-based index (`body[1]text`, `body[2]text`, ...). | *** #### 3) Header Headers are indexed from 1 in Sinch’s parameters (`header[1]`, `header[2]`, ...). **3.1) Header text** | **Latam Template field** | **Sinch Conv API field** | **Notes** | | ------------------------ | ----------------------------- | ------------------------ | | `template.header.title` | `parameters["header[1]text"]` | Used first when present. | **3.2) Header media** | **Latam Template Header field** | **Sinch Conv API field** | **Notes** | | ---------------------------------- | ------------------------------------------ | ---------------------------------------- | | `template.header.document.url` | `parameters["header[1]document.link"]` | Required if document header selected. | | `template.header.document.caption` | `parameters["header[1]document.filename"]` | Only when caption is not blank. | | `template.header.image.url` | `parameters["header[1]image.link"]` | Required if image header selected. | | `template.header.image.caption` | `parameters["body[1]text"]` | Caption is redirected to body parameter. | | `template.header.video.url` | `parameters["header[1]video.link"]` | Required if video header selected. | | `template.header.video.caption` | `parameters["body[1]text"]` | Caption is redirected to body parameter. | **3.3) Header location** | **Latam Template Header Location field** | **Sinch Conv API field** | **Notes** | | --------------------------------------------- | ------------------------------------------- | ---------- | | `template.header.location.geoPoint` latitude | `parameters["header[1]location.latitude"]` | Latitude. | | `template.header.location.geoPoint` longitude | `parameters["header[1]location.longitude"]` | Longitude. | | `template.header.location.name` | `parameters["header[1]location.name"]` | Optional. | | `template.header.location.address` | `parameters["header[1]location.address"]` | Optional. | **3.4) Header parameters array** | **Latam Template Header Parameters field** | **Sinch Conv API field** | **Notes** | | ------------------------------------------ | ----------------------------------- | ---------------------------------- | | `template.header.parameters[index]` | `parameters["header[index+1]text"]` | 1-based index for each text entry. | *** #### 4) Buttons Buttons are indexed from 0 in Sinch’s parameters (`button[0]`, `button[1]`, ...). **4.1) URL and CALL** | **Latam Template Buttons field** | **Sinch Conv API field** | **Notes** | | --------------------------------------------- | --------------------------------------- | ------------------------------------------------ | | `template.buttons[index].type = URL` + `url` | `parameters["button[index]url[1]text"]` | Direct mapping. | | `template.buttons[index].type = CALL` + `url` | `parameters["button[index]url[1]text"]` | Same key path as URL type (value can be `tel:`). | **4.2) QUICK\_REPLY** | **Latam Template Buttons field** | **Sinch Conv API field** | **Notes** | | -------------------------------------- | -------------------------------------------------- | --------------------------------- | | `template.buttons[index].replyPayload` | `parameters["button[index]quick_reply[1]payload"]` | Required for quick reply buttons. | **4.3) FLOW** | **Latam Template Buttons** **field** | **Sinch Conv API field** | **Notes** | | ----------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------- | | `template.buttons[index].flowDetails.type` | `parameters["button[index]flow[1]action.type"]` | Added only when non-null `flowDetails`. | | `template.buttons[index].flowDetails.action.flowToken` | `parameters["button[index]flow[1]action.token"]` | Optional value. | | `template.buttons[index].flowDetails.action.flowActionData` | `parameters["button[index]flow[1]action.data"]` | Optional value. | | `template.buttons[index].flowDetails = null` | *(no parameters)* | Button is skipped for FLOW parameter mapping. | **4.4) ORDER\_DETAILS** | **Latam Template Buttons** **field** | **Sinch Conv API field** | **Notes** | | -------------------------------------------------------- | ---------------------------------------------------------------------- | --------- | | `template.buttons[index].orderDetails.paymentType` | `parameters["button[index]order_details[1]action.type"]` | Optional. | | `template.buttons[index].orderDetails.referenceId` | `parameters["button[index]order_details[1]action.reference_id"]` | Optional. | | `template.buttons[index].orderDetails.type` | `parameters["button[index]order_details[1]action.type_of_goods"]` | Optional. | | `template.buttons[index].orderDetails.totalAmount.value` | `parameters["button[index]order_details[1]action.total_amount_value"]` | Optional. | **4.4.1) ORDER\_DETAILS / order** | **Latam Template Buttons field** | **Sinch Conv API field** | **Notes** | | --------------------------------------- | ---------------------------------------- | --------- | | `...order.subtotal.value` | `...action.order.subtotal_value` | Optional. | | `...order.expiration.timestamp` | `...action.order.expiration_time` | Optional. | | `...order.expiration.description` | `...action.order.expiration_description` | Optional. | | `...order.tax.value` | `...action.order.tax_value` | Optional. | | `...order.tax.description` | `...action.order.tax_description` | Optional. | | `...order.catalogId` | `...action.order.catalog_id` | Optional. | | `...order.shipping.value` | `...action.order.shipping_value` | Optional. | | `...order.shipping.description` | `...action.order.shipping_description` | Optional. | | `...order.discount.value` | `...action.order.discount_value` | Optional. | | `...order.discount.description` | `...action.order.discount_description` | Optional. | | `...order.discount.discountProgramName` | `...action.order.discount_program_name` | Optional. | **4.4.2) ORDER\_DETAILS / items** | **Latam Template Buttons** **field** | **Sinch Conv API field** | **Notes** | | -------------------------------------------- | ----------------------------------------------------- | -------------------------- | | `...order.items[itemIndex].retailerId` | `...action.order.items[itemIndex+1]retailer_id` | 1-based item index in key. | | `...order.items[itemIndex].name` | `...action.order.items[itemIndex+1]name` | 1-based item index in key. | | `...order.items[itemIndex].amount.value` | `...action.order.items[itemIndex+1]amount_value` | 1-based item index in key. | | `...order.items[itemIndex].quantity` | `...action.order.items[itemIndex+1]quantity` | 1-based item index in key. | | `...order.items[itemIndex].saleAmount.value` | `...action.order.items[itemIndex+1]sale_amount_value` | 1-based item index in key. | **4.4.3) ORDER\_DETAILS / payment settings** | **Latam Template Buttons field** | **Sinch Conv API field** | **Notes** | | ---------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `...order.paymentSettings[p].orderPaymentPixSettings.*` | `...action.order.payment_settings[p+1].type = "pix"` + pix fields | Type and fields: `pix_code`, `pix_merchant_name`, `pix_key`, `pix_key_type`. | | `...order.paymentSettings[p].orderPaymentBoletoSettings.*` | `...action.order.payment_settings[p+1].type = "boleto"` + boleto fields | Field: `boleto_digitable_line`. | | `...order.paymentSettings[p].orderPaymentLinkSettings.*` | `...action.order.payment_settings[p+1].type = "payment_link"` + link fields | Field: `payment_link_uri`. | *** #### 5) Legacy HSM | **Latam field** | **Sinch Conv API field** | **Notes** | | ----------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ | | `type = "hsm"` | `message.template_message` | HSM is converted to the same `template_message` output type. | | `hsm.elementName` | `template_message.channel_template.WHATSAPP.template_id` | Required. | | `hsm.languageCode` | `template_message.channel_template.WHATSAPP.language_code` | Required. | | `hsm.parameters[index]` | `parameters["body[index+1]text"]` | Only body parameters are mapped. | *** #### Template With No Parameters Example
Latam Payload ``` { "destinations": [ { "destination": "{{destination_phone_number}}" } ], "message": { "template": { "namespace": "whatsapp:hsm:ecommerce:movile", "elementName": "phone_cta_test", "languageCode": "en", "languagePolicy": "DETERMINISTIC" } } } ``` Conv API Payload ``` { "app_id": "{{conv_api_app}}", "recipient": { "identified_by": { "channel_identities": [ { "channel": "WHATSAPP", "identity": "{{destination_phone_number}}" } ] } }, "message": { "template_message": { "channel_template": { "WHATSAPP": { "template_id": "phone_cta_test", "language_code": "en" } } } } } ``` #### Template With Buttons Example
Latam Payload ``` { "destinations": [ { "destination": "{{destination_phone_number}}" } ], "message": { "template": { "namespace": "whatsapp:hsm:ecommerce:movile", "elementName": "quick_reply_test", "languageCode": "en", "languagePolicy": "DETERMINISTIC", "buttons": [ { "type": "QUICK_REPLY", "replyPayload": "yes" }, { "type": "QUICK_REPLY", "replyPayload": "no" } ] } } } ``` Conv API Payload ``` { "app_id": "{{conv_api_app}}", "recipient": { "identified_by": { "channel_identities": [ { "channel": "WHATSAPP", "identity": "{{destination_phone_number}}" } ] } }, "message": { "template_message": { "channel_template": { "WHATSAPP": { "template_id": "quick_reply_test", "language_code": "en", "parameters": { "button[0]quick_reply[1]payload": "yes", "button[1]quick_reply[1]payload": "no" } } } } } } ``` ## Latam VS Conv API Request Responses ### Success Latam ``` { "id": "18a503fd-f49d-4c9d-88d3-50ab2571a346", "destinations": [ { "id": "c8c17fe2-3151-453b-862d-e8a0ce78ec6e", "destination": "{{destination_phone_number}}" } ] } ``` Conv API ``` { "message_id": "01KRPCBWZR7TNDD8R16DK3KQ87", "accepted_time": "2026-05-15T17:53:51.096Z" } ``` ### Error Latam ``` { "errorCode": 400, "errorMessage": "No WhatsApp messages were found in the request" } ``` Conv API ``` { "error": { "code": 400, "message": "Invalid argument", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.BadRequest", "field_violations": [ { "field": "app_id", "description": "Invalid app_id" } ] } ] } ``` ## Latam VS Conv API Webhooks ### Webhook Configuration In the Sinch Conversation API, webhook URLs are configured at the Conversation API App level. Each Conversation API App is associated with a single business phone number. This means you can configure different webhook URLs for different business phone numbers. **However, unlike the Latam Platform, there is no concept of subaccounts. As a result, it is not possible to route webhooks from the same business phone number to different webhook URLs based on account-level configurations.** To configure webhooks for a specific App, access the [Apps Section on Sinch Build](https://dashboard.sinch.com/convapi/apps) and open the desired App. In the Webhooks section, you can add and manage webhook configurations as described in the following documentation: * [WhatsApp Set Up | Conversation API | Sinch](https://developers.sinch.com/docs/conversation/channel-support/whatsapp/set-up#set-up-the-whatsapp-integration-using-the-sinch-build-dashboard) * [How to add a webhook to a Conversation API app](https://community.sinch.com/t5/Conversation-API/How-to-add-a-webhook-to-a-Conversation-API-app/ta-p/8100) ### Fields Comparison #### 1) Webhook Types | **Latam Webhook** | **Conv API Webhook** | **Notes** | | -------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | sent success status webhook | QUEUED\_ON\_CHANNEL status webhook |

sent success from Latam is equivalent to

message\_delivery\_report.status = QUEUED\_ON\_CHANNEL in Conv API

| | delivered success status webhook | DELIVERED status webhook |

delivered success from Latam is equivalent to

message\_delivery\_report.status = DELIVERED in Conv API

| | read status webhook | READ status webhook |

read from Latam is equivalent to

message\_delivery\_report.status = READ in Conv API

| | failed status webhook | FAILED status webhook |

failed from Latam is equivalent to

message\_delivery\_report.status = FAILED in Conv API

| | MO webhook | MO webhook | `message.direction = TO_APP` contactMessage webhook in Sinch. | *** #### 2) Common wrapper fields (all Latam callbacks) | **Latam field** | **Conv API field** | **Notes** | | ---------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `total` | `-` | Always single webhook in Conv API. | | `clientInfo.customerId` | `-` | similar to `project_id` in Sinch. | | `clientInfo.subAccountId` | `-` | similar to `app_id` in Sinch. | | `clientInfo.userId` | `-` | No dedicated direct field. | | `data[*].campaignAlias` |

If

message\_metadata

| For status: `message_delivery_report.metadata`; | | `data[*].flowId` | Callback metadata JSON | Same metadata source rule as above. | | `data[*].extraInfo` | Callback metadata JSON | Same metadata source rule as above. | | `data[*].correlationId` | `correlationId` | Optional. | | `data[*].origin` | `channel_metadata.whatsapp.sender_phone_number` |

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 - * Programmatically through the Provisioning API - [WhatsApp Templates](https://developers.sinch.com/docs/provisioning-api/api-reference/provisioning-api/whatsapp-templates) The migration should not impact your existing templates. We will synchronize all templates from Latam, making them ready to use in your new Native Conversation API environment once the migration is complete. ## Opt Out There is an important behavioral difference between the legacy Latam Platform and the Conversation API regarding opt-out handling. **In the Conversation API, when a user is identified as opted out and Consent Management is enabled, Sinch blocks all outgoing MT (mobile-terminated) messages for that identity, regardless of the message type. This includes marketing, utility, authentication, service, templated, and non-templated messages.** In contrast, the legacy Latam Platform only blocked marketing templates after an opt-out event. Non-templated messages and authentication/service templates could still be sent to the user even after they opted out. This means the Conversation API provides a stricter and more centralized consent enforcement model, helping ensure compliance across channels and message categories. All Conversation API opt-out and consent management features are available in the official Sinch documentation: * [Consent Management | Sinch](https://developers.sinch.com/docs/conversation/consent-management) - Detailed Documentation * [Consents](https://developers.sinch.com/docs/conversation/api-reference/conversation/consent) - Consent API To use Consent Management, the feature must first be enabled in the Sinch Build Dashboard. Through the Consent API, you can: * Check whether an identity is opted out (using [Get audit records from consent lists](https://developers.sinch.com/docs/conversation/api-reference/conversation/consent/consents_getconsentsauditrecords) endpoint) * Retrieve identities from a consent list (using [Get identities from consent list](https://developers.sinch.com/docs/conversation/api-reference/conversation/consent/consents_getconsents) endpoint) ## Main Differences from Latam Migrating from the legacy Latam platform to the Sinch Conversation API brings architectural changes, including new limitations to be aware of and powerful new capabilities to scale your business. ### Unsupported Features in Conversation API * **Base64 Media Content:** In the legacy Latam platform, you could send media by embedding base64-encoded data directly in the payload. The Sinch Conversation API **does not support base64 media**. All media (images, audio, documents, and videos) must be hosted and sent using publicly accessible URLs. * **MM2 Portal Reports:** The traditional reporting extraction via the Wavy MM2 platform is no longer available. Reporting, delivery receipts, and webhooks are now handled exclusively through the Sinch Conversation API delivery reports and the modern Sinch Customer Dashboard. * **Marketing Templates Only Opt Out:** Unlike the legacy Latam Platform, which only blocked marketing templates after an opt-out event, the Sinch Conversation API blocks all outbound message types for opted-out users. ### Exclusive Conversation API Features * **Continuous API Maintenance:** The Conversation API has a dedicated team continuously improving the platform, adding new capabilities, and ensuring support for the latest Meta features and updates as they are released. * **Direct Send API:** Start conversations with users without needing to create pre-approved templates. * **True Omnichannel Routing:**The Conversation API provides a single, unified REST interface. You build your integration once, and you can reach your customers across **any supported channel** (WhatsApp, SMS, RCS, Instagram, Facebook Messenger, Apple Messages for Business, Viber, etc.) using the exact same API structure. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs-latam.messaging.sinch.com/whatsapp/conversation-api-migration-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.