Nossa solicitação para o URL do Webhook
Quando uma mensagem recebida chega ao seu número de telefone da Twilio, a Twilio envia uma solicitação ao seu aplicativo da Web por meio de uma solicitação de webhook. Esta solicitação contém informações sobre a mensagem recebida, como seu remetente e qualquer mídia anexada. Seu aplicativo pode armazenar esses dados ou usá‐los para personalizar uma resposta, por exemplo.
A Twilio faz solicitações HTTP ao seu aplicativo, assim como um navegador normal da Web, no formato application/x-www-form-urlencoded. Ao incluir parâmetros e valores em suas solicitações, a Twilio envia dados para seu aplicativo para que você possa tomar uma ação com eles antes de responder.
Você pode configurar URLs e métodos HTTP que a Twilio usa para fazer suas solicitações por meio do portal da conta no Console da Twilio ou usando a API REST.
Observação: a Twilio não pode armazenar POSTs em cache. Se você quiser que a Twilio armazene em cache páginas TwiML estáticas, configure‐as para fazer solicitações ao seu aplicativo usando GET.
Parâmetros na Solicitação da Twilio para seu aplicativo
Quando a Twilio recebe uma mensagem em um de seus números da Twilio ou em um número habilitado para WhatsApp, ela faz uma solicitação HTTP síncrona para o URL da mensagem configurada para esse número ou Messaging Service, e espera receber o TwiML em resposta.
A Twilio envia os seguintes parâmetros com sua solicitação como parâmetros POST ou de consulta de URL, dependendo do método HTTP que você configurou:
Parâmetros da solicitação
| PARÂMETRO | DESCRIÇÃO | EXEMPLO |
|---|---|---|
| MessageSid | Um identificador único de 34 caracteres para a mensagem. Pode ser usado para recuperar posteriormente essa mensagem da API REST. | SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| SmsSid | Mesmo valor que MessageSid. Preterido e incluído para compatibilidade com versões anteriores. | SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| AccountSid | O ID de 34 caracteres da Account (conta) à qual esta mensagem está associada. | ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| MessagingServiceSid | O ID de 34 caracteres do Messaging Service associado à mensagem. | MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| From (De) | O número de telefone ou endereço do Canal que enviou esta mensagem. | +14017122661 |
| To (Para) | O número de telefone ou endereço do Canal do destinatário. | +15558675310 |
| Body (Corpo) | O corpo do texto da mensagem. Até 1.600 caracteres. | "Ahoy! Mal podemos esperar para ver o que você vai construir!." |
| NumMedia | O número de itens de mídia associados à sua mensagem | 0 |
| ReferralNumMedia | O número de itens de mídia associados a um anúncio "Click to WhatsApp" (Clique para WhatsApp). | 0 |
Parâmetros relacionados a mídias
A Twilio também envia os seguintes parâmetros quando há mídia, como imagens, associada à mensagem recebida:
| PARÂMETRO | DESCRIÇÃO | EXEMPLO |
|---|---|---|
| MediaContentType{N} | Os ContentTypes para a mídia armazenada no MediaUrl{N}. A ordem do MediaContentType{N} corresponde à ordem do MediaUrl{N}. Se mais de um elemento de mídia for indicado por NumMedia, então MediaContentType{N} será usado, onde N é o índice baseado em zero da mídia (por exemplo, MediaContentType0) |
image/jpeg |
| MediaUrl{N} | Um URL que faz referência ao conteúdo da mídia recebida na mensagem. Se mais de um elemento de mídia for indicado por NumMedia, então MediaUrl{N} será usado, onde N é o índice baseado em zero da mídia (por exemplo, MediaUrl0) |
|
Parâmetros relacionados a dados geográficos
A Twilio também tenta pesquisar dados geográficos com base nos números de telefone "From" (De) e "To" (Para). A Twilio envia os seguintes parâmetros, se disponíveis:
| PARÂMETRO | DESCRIÇÃO | EXEMPLO |
|---|---|---|
| FromCity | A cidade do remetente | SÃO FRANCISCO |
| FromState | O estado ou província do remetente. | CA |
| FromZip | O código postal do remetente chamado. | 94103 |
| FromCountry | O país do remetente chamado. | EUA |
| ToCity | A cidade do destinatário. | SAUSALITO |
| ToState | O estado ou província do destinatário. | CA |
| ToZip | O código postal do destinatário. | 94965 |
| ToCountry | O país do destinatário. | EUA |
Parâmetros específicos do WhatsApp
Para mensagens do WhatsApp, a Twilio envia os parâmetros adicionais:
| PARÂMETRO | DESCRIÇÃO | EXEMPLO |
| ProfileName | O nome do perfil do WhatsApp do remetente | Perspective Coffee |
| WaId | O ID do WhatsApp do remetente (normalmente um número de telefone) | 14017122661 |
| Encaminhada | true se a mensagem tiver sido encaminhada uma vez |
verdadeiro |
| FrequentlyForwarded | true se a mensagem tiver sido encaminhada com frequência |
verdadeiro |
| ButtonText | O texto de um botão de resposta rápida | Cancel Appointment (Cancelar agendamento) |
Para mensagens recebidas do WhatsApp que compartilham uma localização, a Twilio inclui os seguintes parâmetros:
| PARÂMETRO | DESCRIÇÃO | EXEMPLO |
| Latitude | Valor de latitude da localização que está sendo enviada | 51,51322977399644 |
| Longitude | Valor de longitude da localização que está sendo enviada | -0,2197976373036567 |
| Endereço |
Endereço da localização que está sendo enviada |
187 Freston Road, London, Greater London W10 6TH |
| Rótulo |
Rótulo ou nome da localização que está sendo enviada |
The Harrow Club |
Para mensagens recebidas do WhatsApp originadas de um anúncio "Click to WhatsApp" (Clicar para WhatsApp), a Twilio inclui os seguintes parâmetros:
| PARÂMETRO | DESCRIÇÃO | EXEMPLO |
| ReferralBody | Corpo do texto do anúncio | Saiba mais sobre nossa empresa enviando‐nos uma mensagem no WhatsApp |
| ReferralHeadline | Texto do título do anúncio | Envie‐nos uma mensagem |
| ReferralSourceId | ID do anúncio do Meta/WhatsApp | 118588094077142 |
| ReferralSourceType | O tipo do anúncio | postagem |
| ReferralSourceUrl | Um URL que faz referência ao conteúdo da mídia mostrada no anúncio quando o usuário clicou para enviar uma mensagem | https://fb.me/xyz123 |
| ReferralMediaId | ID do Meta/WhatsApp da mídia de anúncio mostrada quando os usuários clicaram para enviar uma mensagem; isso não corresponde ao SID da mídia da Twilio | e420b130-f934-4acf-a5e6-f964f776bxyz |
| ReferralMediaContentType | Media ContentType da mídia do anúncio mostrada ao usuário quando ele clicou para enviar uma mensagem | image/jpeg |
| ReferralMediaUrl | URL que faz referência à mídia exibida ao usuário no anúncio | https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media/MEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
Parâmetros de retorno de chamada de status
Para retornos de chamada de status, a Twilio também envia parâmetros relacionados ao status:
| PARÂMETRO | DESCRIÇÃO | EXEMPLO |
|---|---|---|
| MessageStatus | O status da mensagem. Pode ser: accepted, queued, sending, sent, failed, delivered, undelivered, receiving, received, or read (apenas WhatsApp). Para obter mais informações, consulte descrições detalhadas. |
entregue |
| SmsStatus | Igual ao valor de MessageStatus. Preterido e incluído para compatibilidade com versões anteriores. | entregue |
Retorno de chamada de ErrorCode em mensagens do WhatsApp malsucedidas
Se a entrega de mensagens com o WhatsApp falhar, os parâmetros SmsStatus e MessageStatus serão lidos como undelivered e a Twilio retornará o Erro 63016 como ErrorCode=63016 na resposta do webhook.
Precisa de ajuda?
Às vezes, todos nós precisamos; a programação é difícil. Receba ajuda agora da nossa equipe de suporte, ou confie na sabedoria da multidão navegando pelo Stack Overflow Collective da Twilio ou buscando a tag Twilio no Stack Overflow.
