Mensagens
https://whatsapp.turn.io/v1/messages
Este endpoint é responsável por enviar mensagens via WhatsApp. As mensagens para o WhatsApp são classificadas como:
A API de mensagens de saída da Turn.io é síncrona aos gateways upstream. Se a Turn.io retornar com uma resposta de sucesso, o gateway upstream aceitou a mensagem para entrega. A Turn.io não enfileira mensagens de saída.
Este endpoint é limitado por taxa com base em cada número. Veja limitação de taxa para mais informações.
Mensagens de Texto
$ curl -X POST "https://whatsapp.turn.io/v1/messages" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d '
{
"preview_url": false | true,
"recipient_type": "individual",
"to": "whatsapp-id",
"type": "text",
"text": {
"body": "your-text-message-content"
}
}'
> {
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}
Certifique-se de substituir
tokenpelo seu token de acesso.
Uma resposta bem-sucedida inclui um objeto de mensagens com um identificador para a nova mensagem criada.
Uma resposta mal-sucedida conterá uma mensagem de erro. Veja Códigos de Erro e Status para mais informações.
Parâmetros
| Parâmetro | Obrigatório | Padrão | Descrição |
|---|---|---|---|
| preview_url | não | false | Especificar preview_url na solicitação é opcional quando não incluir uma URL na sua mensagem. Para incluir uma pré-visualização de URL, defina preview_url como true no corpo da mensagem e certifique-se de que a URL comece com http:// ou https://. |
| to | sim | Quando recipient_type é individual, este campo é o ID do WhatsApp (número de telefone) retornado pelo endpoint de contatos. | |
| type | não | text | Especificar type na solicitação é opcional quando você estiver enviando uma mensagem de texto. |
| text.body | sim | O texto a ser enviado |
Mensagens de Mídia
Use o endpoint de mensagens para enviar mensagens contendo áudio, imagens, documentos ou stickers para seus clientes.
Ao enviar uma mensagem que inclui mídia, você deve fornecer o ID da mídia carregada no corpo da solicitação. Também é necessário especificar o tipo de mídia que está sendo enviado: audio, image, video, document ou sticker. Quando a solicitação é recebida, a mídia é carregada no servidor do WhatsApp e enviada ao usuário indicado no campo to.
$ curl -X POST https://whatsapp.turn.io/v1/messages \
-H 'Authorization: Bearer token' \
-H 'Content-Type: application/json' \
-d '
{
"recipient_type": "individual",
"to": "whatsapp-id",
"type": "audio" | "document" | "image" | "sticker" | "video",
"audio": {
"id": "your-media-id",
}
"document": {
"id": "your-media-id",
"caption": "your-document-caption"
}
"image": {
"id": "your-media-id",
"caption": "your-image-caption"
}
"sticker": {
"id": "your-media-id"
}
"video": {
"id": "your-media-id",
"caption": "your-video-caption"
}
}
'
> {
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}
A resposta bem-sucedida inclui um objeto de mensagens com um ID de mensagem.
Uma resposta mal-sucedida conterá uma mensagem de erro. Veja Códigos de Erro e Status para mais informações sobre erros.
Parâmetros
| Nome | Obrigatório | Padrão | Descrição |
|---|---|---|---|
| to | sim | Este campo é o ID do WhatsApp (número de telefone) retornado pelo endpoint de contatos. | |
| type | sim | não | text |
| <media-type>.id | O ID do objeto de mídia, retornado quando a mídia é carregada com sucesso no Cliente da API do WhatsApp Business com o endpoint de mídia. | ||
| <media-type>.caption | Descreve a mídia especificada de imagem ou documento. Não use com mídias audio ou sticker. |
Documentação adicional:
Mensagens de Modelo (Template)
$ curl -X POST https://whatsapp.turn.io/v1/messages \
-H 'Authorization: Bearer token' \
-H 'Content-Type: application/json' \
-d '
{
"to": "whatsapp_id",
"type": "template",
"template": {
"namespace": "template-namespace",
"name": "template-name",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type" : "header",
"parameters": [
{
"type": "text",
"text": "header placeholder value"
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "body placeholder 1 value"
},
{
"type": "text",
"text": "body placeholder 2 value"
}
]
}
]
}
}'
> {
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}
Como nas mensagens normais, a mensagem é enviada ao endpoint /v1/messages. O que difere ao enviar mensagens de modelo (template) é que o tipo de mensagem é definido como template e um objeto template é fornecido com informações, como qual modelo (template) de mensagem usar.
A propriedade template indica o namespace e o nome da mensagem de modelo (template) que deve ser enviado. Ele também inclui uma lista de components que será usada para construir o header, footer, body e buttons do modelo (template).
O namespace pode ser determinado usando o aplicativo web Turn.io da seguinte maneira:
- Navegue para Configurações > API e Webhooks.
- Clique no botão Gerar Credenciais.
- Veja os detalhes da sua API de Mensagens de Modelo (Template), incluindo o namespace e o token de acesso.
Consulte a documentação oficial do WhatsApp para mais detalhes.
Observe que cada novo número está limitado a enviar mensagem de modelo (template) para um máximo de 1000 usuários por dia. À medida que o público total de um número cresce, o WhatsApp aumentará o limite diário conforme os níveis descritos na documentação sobre Avaliação de Qualidade e Limites de Mensagem. O WhatsApp não inicia um número em um nível mais alto e a Turn.io não pode alterar ou solicitar manualmente uma alteração de nível para um número. Os níveis são determinados pelo WhatsApp com base no crescimento orgânico do número e na avaliação geral de qualidade.
Mensagens Interativas
Enviando mensagens com botões de resposta rápida
$ curl -X POST https://whatsapp.turn.io/v1/messages \
-H 'Authorization: Bearer token' \
-H 'Content-Type: application/json' \
-d '
{
"to": "whatsapp_id",
"type": "interactive",
"interactive": {
"type": "button",
"header": { # opcional
"type": "text" | "image" | "video" | "document",
"text": "seu texto"
# OU
"document": {
"id": "seu-id-da-mídia",
"filename": "nome-do-arquivo"
}
# OU
"document": {
"link": "nome-do-provedor/protocolo://a-url",
"provider": {
"name": "nome-do-provedor",
},
"filename": "nome-do-arquivo"
}
# OU
"video": {
"id": "seu-id-da-mídia"
}
# OU
"video": {
"link": "nome-do-provedor/protocolo://a-url",
"provider": {
"name": "nome-do-provedor"
}
}
# OU
"image": {
"id": "seu-id-da-mídia"
}
# OU
"image": {
"link": "http(s)://a-url",
"provider": {
"name": "nome-do-provedor"
}
}
}, # fim do cabeçalho
"body": {
"text": "seu-conteúdo-de-corpo-de-texto"
},
"footer": { # opcional
"text": "seu-conteúdo-de-rodapé-de-texto"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "id-único-de-resposta",
"title": "Título do Primeiro Botão"
}
},
{
"type": "reply",
"reply": {
"id": "id-único-de-resposta",
"title": "Título do Segundo Botão"
}
}
]
}
}
}'
> {
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}
Enviando mensagens em lista
$ curl -X POST https://whatsapp.turn.io/v1/messages \
-H 'Authorization: Bearer token' \
-H 'Content-Type: application/json' \
-d '
{
"to": "whatsapp_id",
"type": "interactive",
"interactive": {
"type": "list",
"header": {
"type": "text",
"text": "seu-conteúdo-de-cabeçalho"
},
"body": {
"text": "seu-conteúdo-de-mensagem-de-texto"
},
"footer": {
"text": "seu-conteúdo-de-rodapé"
},
"action": {
"button": "conteúdo-do-botão-cta",
"sections": [
{
"title":"seu-título-da-seção",
"rows": [
{
"id":"id-único-da-linha",
"title": "conteúdo-do-título-da-linha",
"description": "conteúdo-da-descrição-da-linha",
}
]
},
{
"title":"seu-título-da-seção",
"rows": [
{
"id":"id-único-da-linha",
"title": "conteúdo-do-título-da-linha",
"description": "conteúdo-da-descrição-da-linha",
}
]
}
]
}
}
}'
> {
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}
Enviando mensagens de solicitação de localização
$ curl -X POST https://whatsapp.turn.io/v1/messages \
-H 'Authorization: Bearer token' \
-H 'Content-Type: application/json' \
-d '
{
"to": "whatsapp_id",
"type": "interactive",
"interactive": {
"type": "location_request_message",
"body": {
"type": "text",
"text": "Por favor, informe sua localização?"
},
"action": {
"name": "send_location"
}
}
}'
> {
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrX"
}]
}
Assim como nas mensagens normais, a mensagem é enviada para o endpoint /v1/messages. O que difere ao enviar mensagens interativas é que o tipo de mensagem é definido como interactive, e um objeto interactive é fornecido com informações sobre o tipo de mensagem interativa que você deseja usar, junto com o seu payload. Atualmente, são suportados os tipos button e list.
A propriedade interactive varia dependendo do tipo de mensagem interativa que será enviada (botões ou mensagem em lista). Ela inclui uma propriedade action que será usada para criar o conjunto de opções da mensagem.
Consulte a documentação oficial do WhatsApp para mais detalhes.
Mensagens Interativas com Modelo (Template)
Enviar uma mensagem interativa basicamente significa enviar uma mensagem com modelo (template) usando um modelo que contenha botões.
Consulte a documentação oficial do WhatsApp para mais detalhes.
$ curl -X POST https://whatsapp.turn.io/v1/messages \
-H 'Authorization: Bearer token' \
-H 'Content-Type: application/json' \
-d '
{
"to": "whatsapp_id",
"type": "template",
"template": {
"namespace": "template-namespace",
"name": "template-name",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "valor de espaço reservado 1 no corpo"
}
]
},
{
"type": "button",
"sub_type" : "quick_reply",
"index": "0",
"parameters": [
{
"type": "payload",
"payload": "button-0-payload"
}
]
},
{
"type": "button",
"sub_type" : "quick_reply",
"index": "1",
"parameters": [
{
"type": "payload",
"payload": "button-1-payload"
}
]
}
]
}
}'
> {
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}
Para botões de resposta rápida, é possível fornecer um payload personalizado para cada botão. O payload fará parte da notificação de mensagem recebida que será enviada pelo WhatsApp sempre que o botão for clicado.
Iniciar uma jornada da Turn.io quando um botão de resposta rápida do modelo (template) for clicado
Se você fornecer um paylload de botão no formato turn-start-journey:ID-DA-JORNADA (por exemplo, turn-start-journey:8515561e-2e82-431d-b8f3-e4bac8189183), a Turn.io iniciará a Jornada desejada quando o usuário clicar no botão de resposta rápida do modelo (template).
Aqui está um exemplo que envia um modelo (template) com botões de resposta rápida que iniciarão diferentes jornadas quando clicados:
$ curl -X POST https://whatsapp.turn.io/v1/messages \
-H 'Authorization: Bearer token' \
-H 'Content-Type: application/json' \
-d '
{
"to": "whatsapp_id",
"type": "template",
"template": {
"name": "template-name",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "valor de espaço reservado 1 no corpo"
}
]
},
{
"type": "button",
"sub_type" : "quick_reply",
"index": "0",
"parameters": [
{
"type": "payload",
"payload": "turn-start-journey:018f2df5-3dad-7eb2-b706-8930546a94c6"
}
]
},
{
"type": "button",
"sub_type" : "quick_reply",
"index": "1",
"parameters": [
{
"type": "payload",
"payload": "turn-start-journey:018f2df6-20e0-7354-9f4c-6a3a43daf896"
}
]
}
]
}
}'
> {
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}
Mensagens com Template de Mídia
$ curl -X POST https://whatsapp.turn.io/v1/messages \
-H 'Authorization: Bearer token' \
-H 'Content-Type: application/json' \
-d '
{
"to": "whatsapp_id",
"type": "template",
"template": {
"namespace": "template-namespace",
"name": "template-name",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "video",
"video": {
"link": "https://url.com/video-file.mp4"
}
}
]
}
]
}
}'
> {
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}
Enviar uma mensagem com modelo (template) de mídia significa simplesmente enviar uma mensagem com modelo (template) que tenha um header de mídia. Ao enviar a mensagem com modelo (template), a array components do objeto da solicitação deve fornecer a URL do arquivo de mídia que você pretende enviar dentro do objeto parameters.
Consulte a documentação oficial do WhatsApp para mais detalhes.
Formatação em Mensagens de Texto
O WhatsApp permite algumas formatações em mensagens. Para formatar toda ou parte de uma mensagem, utilize os seguintes símbolos de formatação:
| Formatação | Símbolo | Exemplo |
|---|---|---|
| negrito | Asterisco (*) | Your total is *$10.50*. |
| itálico | Underscore (_) | Welcome to WhatsApp! |
| Til (~) | This is | |
código | Três crases (```) | ```print 'Hello World';``` |
HSM (Descontinuado)
Observe que a funcionalidade HSM foi descontinuada pelo WhatsApp. A versão 2.31 da API WhatsApp Business será a última a suportar esse recurso. Recomendamos a mudança para o novo formato de mensagens template o quanto antes.
$ curl -X POST https://whatsapp.turn.io/v1/messages \
-H 'Authorization: Bearer token' \
-H 'Content-Type: application/json' \
-d '
{
"to": "whatsapp_id",
"type": "hsm",
"hsm": {
"namespace": "8bea15c0_b636_0737_7912_63f2b9a6bd09",
"element_name": "purchase_with_credit_card",
"language": {
"policy": "fallback" | "deterministic",
"code": "en_US"
},
"localizable_params": [
{ "default": "$10" },
{ "default": "1234" }
]
}
}'
> {
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}
Como em outras mensagens, a mensagem é enviada para o endpoint /v1/messages. A diferença ao enviar Modelos (Templates) de Mensagens é o conteúdo do corpo da mensagem especificado pelo parâmetro hsm.
O parâmetro hsm contém um par namespace e element_name que identificam um modelo (template) e os valores a serem aplicados às variáveis nesse modelo.
Documentação adicional para:
- Como criar, enviar e usar modelos (templates) de mensagens
- Os prós e contras dos modelos (templates) de mensagens
Parâmetros Localizáveis para Modelos (Templates) de Mensagens
$ curl -X POST https://whatsapp.turn.io/v1/messages \
-H 'Authorization: Bearer token' \
-H 'Content-Type: application/json' \
-d '
{
"to": "whatsapp_id",
"type": "hsm",
"hsm": {
"namespace": "8bea15c0_b636_0737_7912_63f2b9a6bd09",
"element_name": "purchase_with_credit_card",
"language": {
"policy": "fallback" | "deterministic",
"code": "en_US"
},
"localizable_params": [
{ "default": "$10" },
{ "default": "1234" }
]
}
}
'
O código a seguir fornece um exemplo de envio de um Modelo (Template) de Mensagem. Este exemplo utiliza o nome do elemento purchase_with_credit_card dentro do namespace 8bea15c0_b636_0737_7912_63f2b9a6bd09.
A mensagem resultante recebida pelo cliente será semelhante a esta:
You made a purchase for $10 using a credit card ending in 1234.
Como é possível observar analisando os parâmetros localizáveis e a mensagem recebida pelo cliente, o modelo (template) usou o valor padrão de 10 como o valor da compra e o valor padrão de 1234 como os últimos números do cartão.
Parâmetros
| Nome | Obrigatório | Descrição |
|---|---|---|
| type | sim | Deve ser hsm para mensagens com modelo (template). HSM significa Highly Structured Messages |
| to | sim | O ID do WhatsApp para quem a mensagem está sendo enviada |
hsm | sim | O elemento que contém o conteúdo da mensagem — Indica que a mensagem é altamente estruturada. Os parâmetros contidos fornecem a estrutura. Veja Parâmetros do objeto HSM para mais detalhes. |
Parâmetros do Objeto HSM
| Nome | Obrigatório | Descrição |
|---|---|---|
| namespace | sim | O namespace que será utilizado |
| element_name | sim | O nome do elemento que indica qual modelo (template) utilizar dentro do namespace |
| language | sim | Permite a especificação de uma linguagem determinística ou de fallback. Veja a seção Parâmetros do Objeto Language para mais informações. |
Parâmetros do Objeto Language
O parâmetro language define a política de idioma para um Modelo (Template) de Mensagem; você pode defini-lo como fallback ou deterministic.
| Nome | Obrigatório | Descrição |
|---|---|---|
| policy | sim | A política de idioma que a mensagem deve seguir. Valores possíveis: fallback ou deterministic |
| code | sim | O código do idioma ou localidade a ser utilizado — Aceita formatos de idioma e idioma_localidade (por exemplo, en e en_US). |
Ao enviar um Modelo (Template) de Mensagem, o objeto hsm é obrigatório. Para definir Modelos (Templates) de Mensagens, você especifica um par namespace e element_name que identificam um modelo (template). Os Modelos (templates) têm parâmetros que serão dinamicamente incorporados à mensagem. Para o exemplo usado neste documento, o Modelo (Template) de Mensagem é assim:
"You made a purchase for {{1}} using a credit card ending in {{2}}."
Para "namespace": "8bea15c0_b636_0737_7912_63f2b9a6bd09" com "element_name": "purchase_with_credit_card", o primeiro valor listado substitui a variável {{1}} na mensagem modelo (template), e o segundo valor listado substitui a variável {{2}}.
Observe que o número de parâmetros passados no payload deve corresponder ao número de parâmetros no objeto hsm. Caso contrário, você receberá um callback informando que houve um problema ao exibir o Modelo (Template) de Mensagem.
Alguns desses parâmetros (por exemplo, data/hora ou moeda) são localizáveis para serem exibidos de forma apropriada com base nas preferências de idioma e localidade do cliente. Se o dispositivo não conseguir localizar um parâmetro, ele usará o valor fornecido como 'default'.
As opções de localizable_params são mostradas na tabela abaixo. Para mais informações sobre parâmetros localizáveis, leia a seção Localização.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
default | String | sim | Texto padrão se a localização falhar |
currency | Objeto currency | não | Se o objeto currency for usado, contém os parâmetros obrigatórios currency_code e amount_1000. |
date_time | Objeto date_time | não | Se o objeto date_time for usado, são necessárias definições adicionais da data e hora. Veja o exemplo abaixo para duas das opções. |
Todos os parâmetros localizáveis devem ter um valor padrão. O valor padrão é tudo o que é necessário ao especificar texto.
Entretanto, para especificar moeda e data, além do valor padrão, quando aplicável, utilize os objetos currency e date_time, conforme demonstrado abaixo. Isso permitirá que o cliente tente localizar esses dados da melhor forma possível, utilizando o valor padrão apenas se não conseguir localizá-los. Note que o uso de objetos currency e date_time para parâmetros apropriados é altamente recomendado para oferecer uma experiência localizada ideal aos clientes.
Exemplo de Localização de Modelo (Template)
O exemplo a seguir demonstra o uso de todos os tipos localizáveis atualmente suportados:
$ curl -X POST https://whatsapp.turn.io/v1/messages \
-H 'Authorization: Bearer token' \
-H 'Content-Type: application/json' \
-d '
{
"to": "19195551112",
"type": "hsm",
"recipient_type": "individual",
"hsm": {
"namespace": "8bea15c0_b636_0737_7912_63f2b9a6bd09",
"element_name": "four_lparam_demo",
"language": {
"policy": "deterministic",
"code": "en_US"
},
"localizable_params": [
{
"default": "just a string"
},
{
"default": "$100.99",
"currency": {
"currency_code": "USD",
"amount_1000": 100990
}
},
{
"default": "February 25, 1977",
"date_time": {
"component": {
"day_of_week": 5,
"day_of_month": 25,
"year": 1977,
"month": 2,
"hour": 15,
"minute": 33
}
}
},
{
"default": "January 26, 2017",
"date_time": {
"unix_epoch": {
"timestamp": 1485470276
}
}
}
]
}
}
'