Extensões da API
A API da Turn.io está completamente em linha com a API oficial do WhatsApp Business. No entanto, oferecemos algumas extensões que são expostas por meio de headers HTTP.
Webhooks bidirecionais
Disponibilizamos webhooks para envio de mensagens, além dos webhooks de entrada suportados pela API do WhatsApp Business. A seção sobre webhooks explica isso em mais detalhes.
API de obtenção de mensagens
$ curl -X GET \
-H 'Accept: application/vnd.v1+json' \
-H 'Authorization: Bearer token' \
https://whatsapp.turn.io/v1/contacts/<wa-id>/messages
> '
{
"chat": {
"owner": "<wa-id>",
"assigned_to": {
"id": "account assignment id",
"name": "name of account holder",
"type": "OPERATOR"
} | null,
"state": "OPEN",
"state_reason": "Re-opened by inbound message.",
"unread_count": 1
},
"messages": [{
"to": "wa-id",
"from": "another-wa-id",
"type": "text",
...
"_vnd": {
"v1": {
"direction": "outbound",
"in_reply_to": "an-earlier-inbound-external-id",
"author": {
"name": "the name of the author",
"type": "SYSTEM | OPERATOR"
}
}
}
}]
}
Realizar uma solicitação HTTP GET com nosso header específico do fornecedor Accept: application/vnd.v1+json
desbloqueia essa funcionalidade. Retornamos apenas as 50 mensagens mais recentes enviadas e recebidas para o ID do WhatsApp especificado, ordenadas pelo campo timestamp
em ordem decrescente.
Retornamos a mensagem original do WhatsApp, mas incluímos nossa chave específica do fornecedor _vnd
no payload com informações suplementares que a Turn.io possui em seus registros.
Decidimos expor essa funcionalidade usando headers HTTP para garantir a compatibilidade contínua com a API do WhatsApp Business.
API de obtenção de rótulos
$ curl -X GET \
-H 'Accept: application/vnd.v1+json' \
-H 'Authorization: Bearer token' \
https://whatsapp.turn.io/v1/labels
> '
{
"labels": [{
"uuid": "the-uuid",
"value": "the-label-name",
"color": "the-label-color",
}]
}
Realizar uma solicitação HTTP GET com nosso header específico do fornecedor Accept: application/vnd.v1+json
desbloqueia essa funcionalidade. Retornamos todos os rótulos atualmente vinculados a um número em um único resultado. No futuro, podemos adicionar paginação.
Obtendo mensagens rotuladas
$ curl -X GET \
-H 'Accept: application/vnd.v1+json' \
-H 'Authorization: Bearer token' \
https://whatsapp.turn.io/v1/labels/<label-uuid>/messages
> '
{
"has_more": true,
"next": "/v1/labels/<label-uuid>/messages?p=1",
"message_labels": [{
"confidence": 0.8,
"metadata": {},
"deleted": false,
"message": {
// .. the message payload
}
}]
}
Realizar uma solicitação HTTP GET com nosso header específico do fornecedor Accept: application/vnd.v1+json
desbloqueia essa funcionalidade. Retornamos mensagens em lotes de 50. A resposta indicará se há mais resultados disponíveis para recuperar.
Vinculando uma mensagem de saída a uma de entrada
$ curl -X POST "https://whatsapp.turn.io/v1/messages" \
-H "Authorization: Bearer token" \
-H "X-Turn-In-Reply-To: some-earlier-external-id" \
-H "Content-Type: application/json" \
-d '
{
...
}'
É frequentemente desejável vincular mensagens de saída a mensagens de entrada para auditoria, análise ou treinamento de modelos machine learning. Para fazer isso, adicione nosso header HTTP específico do fornecedor X-Turn-In-Reply-To
com o ID externo que deseja vincular. Não validamos esse valor, ele é armazenado como está.
Quando você recebe uma mensagem de saída via webhooks, agora pode obter a mensagem à qual ela está vinculada.
Arquivando um chat
$ curl -X POST "https://whatsapp.turn.io/v1/chats/<wa-id>/archive" \
-H "Authorization: Bearer token" \
-H "Accept: application/vnd.v1+json" \
-H "Content-Type: application/json" \
-d '
{
"before": "the-message-id",
"reason": "the reason for archiving"
}
'
Pode ser útil arquivar um chat processado de forma automatizada. Para isso, o endpoint de arquivamento de chat espera um parâmetro before
que referencia um ID de mensagem e um parâmetro reason
que contém o motivo do arquivamento.
O chat será arquivado apenas se a última mensagem de entrada recebida no chat for a mesma referenciada pelo parâmetro before
. Caso contrário, o endpoint retornará uma resposta HTTP 200 OK
com o objeto do chat inalterado.
Excluindo um chat
O WhatsApp não suporta a exclusão de chats ou mensagens no dispositivo do destinatário. No entanto, a Turn.io permite que chats sejam excluídos da interface e dos bancos de dados da Turn.io.
Quando um chat é excluído, permanece apenas um único registro anonimizado como um artefato histórico. Todas as mensagens, anexos e detalhes de contato são removidos permanentemente do banco de dados da Turn.io.
$ curl -X DELETE "https://whatsapp.turn.io/v1/chats/<wa-id>" \
-H "Authorization: Bearer token" \
-H "Accept: application/vnd.v1+json" \
-H "Content-Type: application/json"
> {
"chat": {
"state": "CLOSED",
"state_reason": "Chat culled",
"owner": "8bcc8dcf-2c09-473f-92f2-ea12da0ecdb3",
"unread_count": 0
}
}
Se o chat tiver muitas mensagens e anexos, uma única chamada de API pode não ser suficiente para remover todas as mensagens. A API tentará excluir o máximo possível dentro de um único minuto.
Receber um status HTTP 200 OK
com o objeto do chat retornado indica a conclusão bem-sucedida.
Se a resposta for um status HTTP 202 Accepted
com um JSON vazio {}
retornado, será necessário fazer a chamada de API novamente. Continue chamando a API repetidamente até receber uma resposta com status HTTP 200 OK
para garantir a exclusão completa do chat.
Rotulando uma mensagem
$ curl -X POST "https://whatsapp.turn.io/v1/messages/<message-id>/labels" \
-H "Authorization: Bearer token" \
-H "Accept: application/vnd.v1+json" \
-H "Content-Type: application/json" \
-d '{
"labels": ["compliment", "other", {"label": "question", "confidence": 0.9}]
}'
A API permite adicionar rótulos a mensagens. Esses rótulos são automaticamente promovidos ao chat ao qual a mensagem pertence e exibidos na interface do usuário em tempo real. O atributo labels
pode conter uma combinação de strings com nomes de rótulos e/ou objetos JSON com os atributos label
e confidence
.
Marcando uma mensagem como tratada/não tratada
$ curl -X PATCH "https://whatsapp.turn.io/v1/messages/<message-id>" \
-H "Authorization: Bearer token" \
-H "Accept: application/vnd.v1+json" \
-H "Content-Type: application/json" \
-d '{
"is_handled": true
}'
A API permite que operadores humanos ou chatbots marquem mensagens de entrada como tratadas ou não tratadas. Mensagens marcadas como tratadas/não tratadas são exibidas na interface do usuário com um ícone informativo, ajudando o operador humano a identificar perguntas/pedidos pendentes.
O atributo is_handled
é um valor booleano. O valor padrão é null
, caso nunca tenha sido marcado.
Criando uma mensagem de modelo (template)
$ curl -X POST "https://whatsapp.turn.io/graph/v14.0/<your phone number without leading +>/message_templates" \
-H "Content-Type: application/json" \
-d '
{
"access_token": <whatsapp-api-token>,
"category": "ISSUE_RESOLUTION",
"name": "test_template",
"language": "en_US",
"components": [
{
"type": "HEADER",
"format": "TEXT",
"text": "Welcome {{1}}",
"example": {
"header_text": ["Jane", "John"]
}
},
{
"type": "BODY",
"text": "Hi {{1}}, you are now registered as a {{2}}.",
"example":{
"body_text": [
["Jane", "beta tester"],
["John", "support hero"]
]
}
},
{
"type": "FOOTER",
"text": "Thanks again for signing up!"
}
]
}'
A API de mensagens de modelo permite criar mensagens de modelo para aprovação pelo Facebook. É uma API REST que funciona de forma semelhante à Graph API do Facebook.
Observe que esta API está hospedada no caminho graph/
, pois espelha as APIs do Graph do Facebook. Atualmente, suportamos a versão v14.0
da Graph API (no caminho graph/v14.0
).
O payload pode ser enviado como JSON, utilizando a autenticação do tipo Authorization: Bearer ....
Permitimos o envio baseado em formulário e a autenticação baseada em access_token
para garantir compatibilidade.
O campo name é limitado a 512 caracteres. O campo content é limitado a 1024 caracteres.
Os possíveis valores para o campo status
são:
APPROVED
PENDING
REJECTED
PENDING_DELETION
DELETED
Códigos válidos para a categoria category
são:
AUTHENTICATION
MARKETING
UTILITY
Códigos de language válidos são:
af
: Afrikaanssq
: Albanêsar
: Árabeaz
: Azeribn
: Bengalibg
: Búlgaroca
: Catalãozh_CN
: Chinês (CHN)zh_HK
: Chinês (HKG)zh_TW
: Chinês (TAI)hr
: Croatacs
: Tchecoda
: Dinamarquêsnl
: Holandêsen
: Inglêsen_GB
: Inglês (Reino Unido)en_US
: Inglês (EUA)et
: Estonianofil
: Filipinofi
: Finlandêsfr
: Francêsde
: Alemãoel
: Gregogu
: Gujaratiha
: Hausahe
: Hebraicohi
: Hindihu
: Húngaroid
: Indonésioga
: Irlandêsit
: Italianoja
: Japonêskn
: Kannadakk
: Cazaqueko
: Coreanolo
: Laolv
: Letãolt
: Lituanomk
: Macedônioms
: Malaioml
: Malayalammr
: Marathinb
: Norueguêsfa
: Persapl
: Polonêspt_BR
: Português (BR)pt_PT
: Português (POR)pa
: Punjabiro
: Romenoru
: Russosr
: Sérviosk
: Eslovacosl
: Eslovenoes
: Espanholes_AR
: Espanhol (ARG)es_ES
: Espanhol (ESP)es_MX
: Espanhol (MEX)sw
: Suaílisv
: Suecota
: Tâmilte
: Teluguth
: Tailandêstr
: Turcouk
: Ucranianour
: Urduuz
: Uzbequevi
: Vietnamitazu
: Zulu
Listando mensagens de modelo (template)
$ curl -X GET "https://whatsapp.turn.io/graph/v14.0/<your phone number without leading +>/message_templates?access_token=<whatsapp-api-token>"
Você pode usar a API de Gerenciamento do WhatsApp Business para obter uma lista de suas mensagens de modelos (template) existentes.
Mensagens de modelos (template) de mídia
$ curl -X POST "https://whatsapp.turn.io/graph/v14.0/<your phone number without leading +>/message_templates" \
-d 'access_token=<whatsapp-api-token>' \
-d 'category=ISSUE_RESOLUTION' \
-d 'name=test_media_template' \
-d 'language=en_US' \
-d 'components=[
{
"type": "HEADER",
"format": "IMAGE",
"example": {
"header_handle": ["example-file-handle", "another-example-file-handle"]
}
},
{
"type": "BODY",
"text": "Hi {{1}}, you are now registered as a {{2}}.",
"example":{
"body_text": [
["Jane", "beta tester"],
["John", "support hero"]
]
}
}
]'
A API de mensagens de modelo (template) também permite criar modelos (templates) de mídia, que são modelos que incluem um elemento de mídia no cabeçalho. O WhatsApp suporta três tipos de cabeçalhos de mídia para modelos (templates):
TEXT
: Um cabeçalho de texto padrão.DOCUMENT
: Cabeçalho que inclui um documento PDF.VIDEO
: Cabeçalho que inclui um vídeo.IMAGE
: Cabeçalho que inclui uma imagem.
Esta API imita o comportamento da API de Mensagens de Modelo (Template) do Facebook Graph. Para mais detalhes, consulte a documentação oficial em developers.facebook.com.
Exemplo de Mídia
Para facilitar a aprovação do seu modelo pelo Facebook, você deve fornecer um ou mais arquivos de mídia de exemplo que representem o tipo de imagens/vídeos/documentos que serão usados ao enviar mensagens com base no modelo.
Para isso, primeiro é necessário fazer o upload da(s) mídia(s) de exemplo usando a API de Upload Recomeçável e, em seguida, fornecer o(s) identificador(es) de arquivo retornado(s) por essa API no campo example -> header_handle
do componente HEADER
(veja o exemplo à direita).
Mensagens de modelo (template) interativas
$ curl -X POST "https://whatsapp.turn.io/graph/v14.0/<your phone number without leading +>/message_templates" \
-d 'access_token=<whatsapp-api-token>' \
-d 'category=ISSUE_RESOLUTION' \
-d 'name=test_interactive_template' \
-d 'language=en_US' \
-d 'components=[
{
"type": "HEADER",
"format": "TEXT",
"text": "Welcome {{1}}",
"example": {
"header_text": ["Jane", "John"]
}
},
{
"type": "BODY",
"text": "Hi {{1}}, you are now registered as a {{2}}.",
"example":{
"body_text": [
["Jane", "beta tester"],
["John", "support hero"]
]
}
},
{
"type": "FOOTER",
"text": "Thanks again for signing up!"
},
{
"type": "BUTTONS",
"buttons":[
{
"type": "PHONE_NUMBER",
"text": "Call us",
"phone_number": "+1(650) 555-1111"
},
{
"type": "URL",
"text": "Visit out website",
"url": "https://www.website.com/{{1}}",
"example": ["https://www.website.com/welcome", "https://www.website.com/register"]
}
]
}
]'
A API de mensagens de modelo (template) também permite criar modelos (templates) interativos. Modelos (Templates) interativos são modelos (templates) de mensagem que incluem um componente do tipo BUTTONS
, contendo uma lista de botões.
O WhatsApp suporta três tipos de botões:
PHONE_NUMBER
: Um botão que disca para um número de telefone ao ser clicado.URL
: Um botão que abre uma URL ao ser clicado.QUICK_REPLY
: Um botão que envia uma resposta automática ao ser clicado.
Esta API imita o comportamento da API de Mensagem de Modelo (Template) Interativa do Facebook Graph. Para mais detalhes, consulte a documentação oficial em developers.facebook.com.
API de upload recomeçável
$ curl -X POST "https://whatsapp.turn.io/graph/v14.0/app/uploads" \
-d 'number=<your phone number without leading +>' \
-d 'access_token=<whatsapp-api-token>' \
-d 'file_length=<file-length-in-bytes>' \
-d 'file_type=<file-mime-type>'
> {"id":"<upload-session-id>"}
# A chamada de API anterior retorna um <upload-session-id>,
# que é necessário como parte da URL para a próxima chamada.
$ curl "https://whatsapp.turn.io/graph/<upload-session-id>" \
-F 'number=<your phone number without leading +>' \
-F 'access_token=<whatsapp-api-token>' \
-F 'file=@"/path/to/media/file.extension"' \
-H 'file_offset: 0'
> {"h":"<file-handle>"}
# A chamada de API anterior retorna um <file-handle>,
# que pode ser usado ao criar um modelo (template) de mídia.
A API de upload recomeçável permite enviar arquivos de mídia para o Facebook e retorna file handles que podem ser usados para especificar exemplos ao criar modelos de mídia.
O upload acontece em duas etapas:
- Uma primeira chamada de API para iniciar a sessão de upload.
- Uma segunda chamada de API para fazer o upload do arquivo de mídia via
multipart/form-data
usando a sessão iniciada.
A segunda chamada de API faz o upload do arquivo de mídia para o Facebook e retorna um ID denominado file handle (uma string semelhante a 4::###
).
Ao especificar o tipo de arquivo, use um tipo MIME padrão, como image/jpeg
, video/mp4
, etc.
Reivindicação de Conversação
A Turn.io permite delegar o controle de uma conversa com um indivíduo para um sistema externo por um período limitado de tempo.
Estender um lease para um sistema externo significa que todos os webhooks e todas as automações configuradas na Turn.io são ignorados durante o período do lease para essa conversa.
Isso pode ser feito na seção de Automação na interface do Turn.io.
Para garantir que um webhook seja adequado para a reivindicação de conversação, primeiro adicione-o como um webhook normal nas configurações de Webhooks, marque-o como habilitado, mas não configure para receber mensagens de entrada ou saída.
Isso garante que o webhook seja registrado na Turn.io, mas não receba automaticamente nenhum tráfego de mensagens.
Em seguida, configure a automação selecionando um gatilho apropriado. Para o Passo 2, Adicionar uma Ação, selecione a ação Chamar um webhook.
No Passo 3, selecione o webhook que deve receber o tráfego de entrada como resultado de um gatilho de ação específico.
$ curl -X POST "https://whatsapp.turn.io/v1/messages" \
-H "Authorization: Bearer token" \
-H "X-Turn-Claim-Extend: <claim-uuid>" \
-H "Content-Type: application/json" \
-d '
{
"preview_url": false | true,
"to": "whatsapp-id",
"type": "text",
"text": {
"body": "your-text-message-content"
}
}'
> {
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}
$ curl -X POST "https://whatsapp.turn.io/v1/messages" \
-H "Authorization: Bearer token" \
-H "X-Turn-Claim-Release: <claim-uuid>" \
-H "Content-Type: application/json" \
-d '
{
"preview_url": false | true,
"to": "whatsapp-id",
"type": "text",
"text": {
"body": "your-text-message-content"
}
}'
> {
"messages": [{
"id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
}]
}
$ curl -X POST "https://whatsapp.turn.io/v1/messages/<message-id>/automation" \
-H "Authorization: Bearer token" \
-H "X-Turn-Claim-Release: <claim-uuid>"
> {}
Certifique-se de permitir que o webhook reivindique a conversa usando o botão de alternância.
Quando o gatilho for acionado, um lease será criado para a conversa em questão.
Seu webhook receberá uma solicitação HTTP com um cabeçalho X-Turn-Claim: <claim-uuid>
. Esse lease dura no máximo 5 minutos.
O webhook tem 5 minutos para responder, caso contrário, a Turn.io expirará o lease e retomará o controle da conversa.
O webhook pode fazer 2 coisas com esse lease para mensagens de saída enviadas ao endpoint /v1/messages
:
- Pode definir o cabeçalho de solicitação HTTP
X-Turn-Claim-Extend: <claim-uuid>
para estender o lease por mais 5 minutos. - Pode definir o cabeçalho de solicitação HTTP
X-Turn-Claim-Release: <claim-uuid>
para liberar o lease e delegar o controle de volta para a Turn.io.
Finalmente, existe um caso em que a resposta final deve enviar a última mensagem submetida de volta à Turn.io para reavaliação pelas regras de automação.
Enviar um POST HTTP para /v1/messages/<message-id>/automation
com o cabeçalho HTTP X-Turn-Claim-Release: <uuid>
definido resulta na liberação do lease e no reenvio da mensagem para a Turn.io para avaliação na Automação.
O caso de uso aqui é quando o webhook que reivindica a conversa pode fornecer um fallback para a Turn.io, como funcionalidade "Responda 📌 Menu para retornar ao menu principal".
Gerenciando Reivindicações de Conversação
Às vezes, pode ser necessário obter os detalhes de, ou excluir, uma reivindicação de conversa para um único número. Isso é útil quando você deseja liberar uma reivindicação em uma conversa sendo gerenciada por um sistema específico que teve algum problema, como um loop ou timeout que torna a conversa inadministrável. Este endpoint permite obter os detalhes de uma única reivindicação e/ou excluí-la. Este recurso é principalmente para fins de depuração e não é destinado para uso em grande escala.
$ curl -X GET "https://whatsapp.turn.io/v1/contacts/<wa_id>/claim" \
-H "Authorization: Bearer token" \
-H "Accept: application/vnd.v1+json"
> {
"claimed_at" : "2023-05-06T10:19:00.791854Z",
"claimed_until" : "2023-05-09T10:19:00.801389Z",
"inserted_at" : "2023-05-08T10:19:00.801498Z",
"message_uuid" : "6f988bca-462e-407e-afa4-1d7c3a3fc4f6",
"metadata" : {},
"scope" : "stack",
"scope_id" => "503db06f-0f29-41f4-8287-57326e9f4217",
"updated_at" : "2023-05-08T10:19:00.801498Z",
"uuid" : "f9dc8f9a-3b77-4a74-aeed-551cd51cb432"
}
e para excluir a reivindicação:
$ curl -X DELETE "https://whatsapp.turn.io/v1/contacts/<wa_id>/claim" \
-H "Authorization: Bearer token" \
-H "Accept: application/vnd.v1+json"
> {"claim_uuid": "f9dc8f9a-3b77-4a74-aeed-551cd51cb432"}
Gerenciando Conteúdo
A Turn.io permite que conteúdos, FAQs e Automators sejam importados e exportados via API. Isso pode ser útil para serviços de tradução ou para integrar a Turn.io ao seu próprio pipeline de informações.
Exportando Conteúdo
$ curl -X GET "https://whatsapp.turn.io/v1/export" \
-H "Authorization: Bearer token" \
-H "Accept: application/vnd.v1+json" > content.json
Por padrão, a resposta incluirá apenas itens de FAQ e Automator que não foram marcados como excluídos no banco de dados por meio da propriedade is_deleted
. Se o consumidor desejar incluir itens excluídos, é possível especificar o parâmetro de consulta include_deleted
:
$ curl -X GET "https://whatsapp.turn.io/v1/export?include_deleted=true" \
-H "Authorization: Bearer token" \
-H "Accept: application/vnd.v1+json" > content.json
A resposta dessa API pode ser usada como entrada válida para as APIs de importação descritas abaixo.
Importando Conteúdo
Ao usar o método HTTP POST
, o conteúdo existente será excluído, e apenas o conteúdo presente na importação estará disponível após sua conclusão.
Se a importação falhar, nenhum conteúdo será excluído.
$ curl -X POST "https://whatsapp.turn.io/v1/import" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.v1+json" \
-d @content.json
Atualizando Conteúdo
Ao usar o método HTTP PUT
, o conteúdo existente NÃO será excluído. O conteúdo será atualizado se uma entrada correspondente com o mesmo UUID for encontrada.
Entradas presentes na importação sem um UUID serão criadas.
Se a importação falhar, nenhum conteúdo será modificado.
$ curl -X PUT "https://whatsapp.turn.io/v1/import" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.v1+json" \
-d @content.json
Este endpoint também pode ser usado para excluir e restaurar dados de FAQ e Automator, modificando a propriedade is_deleted
dos itens com um UUID correspondente.