Serviço responsável pelo envio de mensagens por WhatsApp.
Esta documentação tem como objetivo instruir sobre a utilização da mesma, demonstrando como realizar o envio de mensagens.
Documentação de Uso da API de WhatsApp.
Para utilizar os Micro Serviços Flex, é necessário um Login/ Senha fornecido pela equipa de TI. Ao realizar a validação de Login, em caso de positivo o mesmo gera um token de acesso, os login são de uso restrito e podem ser usados para todos os Micro Serviços na qual ele tem acesso.
Todas as requisições POST - Json para o API devem conter o campo de token no primeiro campo do JSON (com exceção dos métodos de Login/ Consulta Token). Todas as requisições GET - Json para o API devem conter o campo de token na URL de solicitação (com exceção dos métodos de Login/ Consulta Token).
O token de acesso tem validade de no máximo 6 horas, após este periodo, deve-se logar novamente para gerar um novo Token.
POST - https://apiwp.code7.com/Messaging/Login
Exemplo de JSON de Login, substitua as informações abaixo por suas credenciais.
{
"login": "flex.flex",
"password": "12345678"
}
Método genérico de envio de mensagens para WhatsApp, WhatsApp Expresso. Estes envios serão realizados pelo método Send.
Todos os envios estarão atrelados a uma campanha.
Método utilizado para enviar a mensagens, tanto mensagens HSM (Highly Structured Message) ou mensagens de texto simples (Text) para WhatsApp.
Text: Mensagens de texto de WhatsApp simples.
As mensagens de texto simples só poderão ser enviadas se já existir uma mensagem HSM respondida nas últimas 24 horas (Regra não se aplica para mensagem de chat sem whatsapp).
HSM/ Template: Mensagens estruturadas que contém um namespace vinculado a um template pré-definido, sendo possível realizar a substituição de variáveis em seu texto. Exemplo: {{1}}. Baseado em seu último atendimento por {{2}}, o quanto você recomendaria o seu {{3}} para um amigo? De uma nota de 0 a 10. Comente. Onde {{1}} será o campo01, {{2}} o campo02 e assim sucessivamente.
Quick Replies: Mensagens estruturadas que contém um namespace vinculado com frase(HSM) e opções de botões pré-definidos. Existe a possibilidade de incluir ao template até 3 tipos de botões pré definidos, que são Texto de até 20 Caracteres para resposta rápida ao clicar, Número Telefônico para Ligação ao clicar e URL fixa para acesso ao clicar.
Exemplo:
As mensagens de Templae HSM e Template Quick Replies precisam de aprovação previa do Fabebook(WhatsAPP) para ser utilziada, e não podem ser alteradas após aprovada. A aprovação pode levar até 7 Dias.
POST - https://apiwp.code7.com/Messaging/Send
Para realizar a requisição do envio de mensagem é necessário enviar o objeto como array.
Para envios em massa, utilizar somente até no máximo 1000 registros por POST, para Lotes maiores, quebrar o lote de envio em duas ou mais postagens de 1000 conforme a quantidade que deseja enviar.
Os campos utilizados estão descritos abaixo:
| Campo | Tipo | Descrição | Parâmetro | Obrigatório |
|---|---|---|---|---|
| token | string | Token de retorno obtido após o Login na Api. | Json | |
| codCampaign | integer | Código da campanha relacionado ao envio das mensagens. | Json | |
| ID | string | Id de envio de mensagem enviado para identificação, caso não será enviado, será gerado um id randômico. | Json | |
| Telephone | string | Número do telefone que receberá a mensagem. | Json | |
| CodNameSpace | integer | Código do namespace da mensagem HSM. | Json | |
| field01 to 20 | string | Estes campos armazenarão dados para substituição da informação na mensagem HSM. | Json | |
| Message | string | Texto da mensagem simples. | Json | |
| Type | string | Tipo do arquivo da media que está sendo enviado. Estes tipos poderão ser document, image, audio ou video. Para o tipo document serão aceitos arquivos doc, docx, ppt, pptx, xls, xlsx e pdf. Para o tipo image serão aceitos arquivos jpeg, png, gif, bmp e webp. Para o tipo audio, serão aceitos os arquivos AAC, M4A, AMR, MP3, OGG e OPUS. Para o tipo video, sera aceito o arquivo M4A. | Json | |
| idMedia | string | Id de identificação da media recebido através do método de uploadfile. | Json | |
| callbackStatus | string | (Atenção: Item disponível somente para Whatsapp Bussines) URL de Webhook de status, quando este campo é informado os status referentes a este envio deixa de ser enviado ao webhook que pertence a campanha e é direcionado exclusivamente para a URL informada, a mesma deve ser válida e estar Online no momento que o evento ocorrer, caso contrário o evento não sera reenviado. Os demais envios sem este campo não são afetados e os eventos seguem sendo entregues na URL cadastrada na Campanha. | Json | |
| callbackResponses | string | (Atenção: Item disponível somente para Whatsapp Bussines) URL de Webhook de respostas, quando este campo é informado as respostas referentes a este envio deixa de ser enviado ao webhook que pertence a campanha e é direcionado exclusivamente para a URL informada, a mesma deve ser válida e estar Online no momento que o evento ocorrer, caso contrário o evento não sera reenviado. Os demais envios sem este campo não são afetados e os eventos seguem sendo entregues na URL cadastrada na Campanha. | Json | |
| hashCodeId | string | (Atenção: Item disponível somente para Whatsapp Expresso) Mensagem que usam o hashCodeId como identificador e nao precisam de validação de token, telefone, campanha e id. O hashCodeId é obtido no envio de uma primeira mensagem Send ao destino e tem duração de 24h. | Json |
Campo 'Telephone'
Deve ser informado o número completo do telefone, portanto é necessário informar o DDI + Número de província caso exista (DDD) + Telefone.
Campo 'Type'
Em caso de envio de MEDIA, atenção ao campo Type, é importante informar o type correto para que sua media seja entregue. Alguns Brokers podem possuir retriçoes a algumas extençoes específicas como no caso de DOC e XLS e nao entregar a Media, consulte o time da mensageria para mais informaçoes.
Exemplo do JSon de Envio para mensagens HSM e mensagens Quick Replies, substitua as informações abaixo de token pelo token obtido no Login.
[
{
"token": "token",
"Id": "teste0001",
"codCampaign": 1,
"Telephone": "5511980125654",
"codNamespace": 1,
"field01": "Teste01",
"field02": "Teste02",
"field03": "Atendimento"
}
]
Exemplo do JSon de Envio para mensagens de texto simples, substitua as informações abaixo de token pelo token obtido no Login.
[
{
"token": "token",
"Id": "teste0007",
"codCampaign": 1,
"Telephone": "5511980125654",
"Message": "Envio Teste"
}
]
Exemplo do JSon de Envio para mensagens com media, substitua as informações abaixo de token pelo token obtido no Login.
[
{
"token": "token",
"Id": "Teste_0001",
"codCampaign": 1,
"Telephone": "5511980125654",
"Type": "image",
"idMedia": "xyzxyx-xyz"
}
]
Exemplo do JSon de Envio para mensagens de texto simples com Emoji. Utilize caracteres Emoji UTF-8/ UTF-16, substitua as informações abaixo de token pelo token obtido no Login.
[
{
"token": "token",
"Id": "teste0007",
"codCampaign": 1,
"Telephone": "5511980125500",
"Message": "Ola Teste 😱😥😕😒👍😁 "
}
]
Exemplo de Json de Envio em Lote, substitua as informações abaixo de token pelo token obtido no Login.
[
{
"token": "token",
"codCampaign": 1,
"Id": "teste100",
"Telephone": "5511980125654",
"Message": "Envio Teste"
},
{
"token": "token",
"codCampaign": 1,
"Id": "teste1002",
"Telephone": "5511981250477",
"Message": "Envio Teste"
}
]
Exemplo do JSon de Envio para mensagens com URL de callbacks exclusiva, substitua as informações abaixo de token pelo token obtido no Login.
[
{
"token": "token",
"Id": "teste0007",
"codCampaign": 1,
"Telephone": "5511980125654",
"Message": "Envio Teste",
"callbackResponses": "http://dominiourl/callback/resposta",
"callbackStatus": "http://dominiourl/callback/status"
}
]
Exemplo do JSon de Envio para mensagens expressas de Whastsapp, mensagem que usam o hashCodeId como identificador e nao precisam de validação de token, telefone, campanha e id. O hashCodeId é obtido no envio de uma primeira mensagem Send ao destino e tem duração de 24h.
[
{
"hashCodeId": "Xc34b6ff-e503-4a14-a8cb-93b270c567be",
"Message": "Envio Teste 2"
}
]
Exemplo do JSon de Envio para mensagens HSM que contém Documentos, Imagens ou Videos em seu template, substitua as informações abaixo de token pelo token obtido no Login.
[
{
"token": "token",
"Id": "teste0001",
"codCampaign": 1,
"Telephone": "5511980125654",
"codNamespace": 1,
"Message": "Nome Arquivo",
"idMedia": "A817hx018-198nd-we"
}
]
Exemplo do JSon de retorno.
[
{
"id": "teste0001-01",
"telephone": "5511910101010",
"status": "OK - Text",
"parts": "1",
"hashCodeId": "9c34b6ff-e503-4a14-a8cb-93b270c567bx"
}
]
Método utilizado para realizar o upload de medias.
Para o tipo de media document serão aceitos arquivos doc, docx, ppt, pptx, xls, xlsx e pdf. Para o tipo image serão aceitos arquivos jpeg, png, gif, bmp e webp. Para o tipo audio, serão aceitos os arquivos AAC, M4A, AMR, MP3, OGG e OPUS. Os arquivos terão validade de até 30 dias.
POST - https://apiwp.code7.com/Messaging/UploadFile
Content-Type : multipart/form-data File : (seu arquivo)
| Campo | Tipo | Descrição | Parâmetro | Obrigatório |
|---|---|---|---|---|
| File | form-data | Arquivo de media para realizar upload. | form-data |
Exemplo do JSon de retorno.
{
"idMedia": "xyzxyx-xyz",
"validUntil": "2018-09-30"
}
Método utilizado para transferir o histórico da conversa WhatsApp entre as campanhas cadastras, o mesmo deve ser utilizado entre campanhas de Whatsapp na qual têm Callback de Mensagem cadastradas (ver, Webhook Mensagem), ao acionar o Transfer To Campaign a última sessão de histórico de conversa é enviado a nova campanha, para assim a mesma continuar a tratativa e é criada uma nova sessão a partir deste ponto. As sessões por padrão são consideradas até as últimas 24h, porem esta período pode ser configurado conforme a campanha.
É enviado um JSON inicial de WhatsappTransfer avisando que se inicia um trasnferencia, com as informaçoes do cliente, apos este enviamos, sera enviado os JSONs com o historico, catalogados como WhatsappHistory.
Após a transferência, todas as novas interações serão direcionadas para a Nova Campanha por um perídio pré-definido, por default está definido para as próximas 24h, porem este tempo pode ser configurável conforme a campanha.
Os campos utilizados estão descritos abaixo.
POST - https://apiwp.code7.com/Messaging/TransferToCampaign
| Campo | Tipo | Descrição | Parâmetro | Obrigatório |
|---|---|---|---|---|
| token | string | Token de retorno obtido após o Login na Api. | Json | |
| codCampaign | string | Cod. da campanha atual atrelada à as mensagens. | Json | |
| codCampaignNew | string | Cod. da campanha nova campanha na qual serra realizada a transferência. | Json | |
| Telephone | string | Número de telefone na qual pertence o histórico de transferência. | Json | |
| TreeMenu | string | Em caso de arvore de decisão antes da transferência, este campo é enviado com o fluxo da conversa. Enviar a estrutura de arvore conforme esperado pela nova campanha. | Json |
Exemplo do JSon para transferir a campanha, substitua as informações abaixo de token pelo token obtido no Login.
{
"token": "token",
"codCampaign": "1",
"codCampaignNew": "13",
"Telephone": "5511999889988"
}
Exemplo do JSon de WhatsappTransfer que será transmitido ao inicar a transferência ao Callback da nova campanha.
{
"id": "3AA05321A7",
"codCampaign": "1",
"Telephone": "5511999889988",
"Date": "2018-05-17 19:38:26",
"message": "TRANSFERED CAMPAIGN",
"contact": "Jose da Silva",
"lastAnswer": "Quero falar com um atendente.",
"treeMenu": "1;3;1",
"type": "WhatsappTransfer"
}
Exemplo do JSon de WhatsappHistory que será transmitido ao Callback da nova campanha.
{
"id": "3AA05321A7",
"codCampaign": "13",
"Telephone": "5511999889988",
"Date": "2018-05-17 19:38:26",
"message": "Teste",
"client": "YES",
"contact": "Jose da Silva",
"type": "WhatsappHistory"
}
Método utilizado para limpar a sessão do Telefone informado, o mesmo só deve ser acionado quando o Telefone foi transferido para uma nova campanha, porem o solicitante quer que este Telefone volte para a Origem.
Ao utilizar este método, todas as sessões do número de Telefone informado são limpas. Não utilize o mesmo caso o número não seja de uma transferência.
O tempo de retorno do POST pode variar de acordo com o tamanho da sessão (quantidade de interações) do Telefone informado.
Os campos utilizados estão descritos abaixo.
POST - https://apiwp.code7.com/Messaging/TransferToCampaign/EndSession
| Campo | Tipo | Descrição | Parâmetro | Obrigatório |
|---|---|---|---|---|
| token | string | Token de retorno obtido após o Login na Api. | Json | |
| Telephone | string | Número de telefone na qual pertence o histórico de interações. | Json |
Exemplo do JSon para encerrar a sessão, substitua as informações abaixo de token pelo token obtido no Login.
{
"token": "token",
"Telephone": "5511999889988"
}
Exemplo do JSon de retorno.
[
{
"telephone": "551198987458",
"status": "OK - All sessions have ended"
}
]
As atualizações são enviadas através de Webhook.
Após criar o hook e enviar sua URL de Webhook as funcionalidades de callback estão ativas.
Para identificar o retorno da mensagem, é necessário criar um webhook em um endereço configurado, assim o mesmo irá enviar o retorno da mensagem quando um evento acontece através de um JSon.
O JSon de retorno de mensagens conterá o campo message e não terá o campo Url, já o Json de retorno de media, conterá o campo Url e não terá o campo message.
Em alguns casos isolados em números do BRASIL, DDD 55 o Whatsapp pode enviar a Mensagem de Resposta com o Telefone (Campo Telephone) sem o nono digito. (Exemplo: 554881828384 ao invés de 5548981828384).
Este comportamento é próprio da Plataforma Meta Whatsapp e não um problema na API, para esses casos, basta sempre responder para o mesmo número de Telefone que chegou no Call-back, seja ele com 12 ou 13 Dígitos.
| Campo | Tipo | Descrição |
|---|---|---|
| id | string | ID único de identificação. |
| codCampaign | string | cod. da campanha atrelada à mensagem enviada. |
| Telephone | string | Número do Telefone enviado. |
| Date | string | Data do evento (GMT-3). |
| message | string | Mensagem respondida pelo número enviado/ url de Media respondida pelo número. |
| contact | string | Nome do respondente (Obs: Este campo é enviado somente quando a informação está disponível por parte do Broker) |
| client | string | Classificação se a mensagem de histórico é do cliente ou da plataforma (Obs: Este campo é enviado somente no Transfer To Campaing contrnado a informaçao de YES/ NO) |
| subtitleMedia | string | Texto de legenda das Medias enviadas, caso exista (Obs: Este campo é valido somente para alguns fornecedores) |
| lastAnswer | string | Última mensagem do cliente antes da transferência (Obs: Este campo é enviado somente no Transfer To Campaing). |
| treeMenu | string | Em caso de arvore de decisão antes da transferência, este campo é enviado com o fluxo da conversa (Obs: Este campo é enviado somente no Transfer To Campaing). |
| type | string | Tipo da mensagem envida. |
| Url | string | Url onde o arquivo de media será disponibilizado. |
| longitude | string | Campo com a informação de longitude referente a Localização enviada (Obs: Este campo é valido somente para alguns fornecedores). |
| latitude | string | Campo com a informação de latitude referente a Localização enviada (Obs: Este campo é valido somente para alguns fornecedores). |
| startMetaSession | timestamp | Campo em Timestamp Unix GMT-3 com a informação de inicio da Sessão atual de 24h com a Meta Facebook (Obs: Este campo é valido para Whatsapp Bussines). |
Exemplo do JSon de resposta Whatsapp.
{
"id": "XYZ123",
"codCampaign": "1",
"Telephone": "551199999999",
"Date": "2018-05-17 19:38:26",
"message": "Teste",
"type": "WhatsappText"
}
Exemplo do JSon de resposta Whatsapp com Contact.
{
"id": "3AA05321A799714AADE8",
"codCampaign": "1",
"Telephone": "551199999999",
"Date": "2018-05-17 19:38:26",
"message": "Teste",
"contact": "Jose da Silva",
"type": "WhatsappText"
}
Exemplo do JSon de envio para mensagens de WhatsApp com media.
{
"id": "3AA05321A799714AADE8",
"codCampaign": "1",
"Telephone": "551199999999",
"Date": "2018-05-17 19:38:26",
"message": "https://URL/file",
"type": "WhatsappMedia"
}
Exemplo do JSon de envio para mensagens de WhatsApp com media, contendo legenda na Imagem.
{
"id": "3AA05321A799714AADE8",
"codCampaign": "1",
"Telephone": "551199999999",
"Date": "2018-05-17 19:38:26",
"message": "https://URL/file",
"subtitleMedia": "Texto na Imagem",
"type": "WhatsappMedia"
}
Exemplo do JSon de envio para mensagens de chat sem whatsapp.
{
"id": "id0001",
"codCampaign": "171",
"Date": "2018-02-08 10:45:03",
"message": "ola, tudo bem?",
"type": "ChatText"
}
Exemplo do JSon de envio para aviso de transferência.
{
"id": "3AA05321A7",
"codCampaign": "13",
"Telephone": "5511999889988",
"Date": "2018-05-17 19:38:26",
"message": "TRANSFERED CAMPAIGN",
"contact": "Jose da Silva",
"lastAnswer": "Quero falar com um atendente.",
"treeMenu": "1;3;2",
"type": "WhatsappTransfer"
}
Exemplo do JSon de envio para mensagens de transferência.
{
"id": "3AA05321A7",
"codCampaign": "13",
"Telephone": "5511999889988",
"Date": "2018-05-17 19:38:26",
"message": "Teste",
"client": "YES",
"contact": "Jose da Silva",
"type": "WhatsappHistory"
}
Exemplo do JSon de Localização Whatsapp.
{
"id": "XYZ123",
"codCampaign": "1",
"Telephone": "551199999999",
"Date": "2018-05-17 19:38:26",
"message": "Teste",
"longitude": "-46.689845",
"latitude": "-23.571829",
"type": "WhatsappLocation"
}
Exemplo do JSon de resposta Whatsapp com startMetaSession.
{
"id": "XYZ123",
"codCampaign": "1",
"Telephone": "551199999999",
"Date": "2018-05-17 19:38:26",
"message": "Teste",
"startMetaSession": 1643198640,
"type": "WhatsappText"
}
Para identificar o retorno do status, é necessário criar um webhook em um endereço configurado, assim o mesmo iria enviar o retorno da mensagem quando um evento acontece através de um JSon.
| Campo | Tipo | Descrição |
|---|---|---|
| id | string | ID único de identificação. |
| codCampaign | string | cod. da campanha atrelada à mensagem enviada. |
| Telephone | string | Número do Telefone enviado. |
| Date | string | Data do evento. |
| status | string | Status de envio. |
| type | string | Tipo do status envida. |
Exemplo do JSon de status Whatsapp.
{
"id": "3AA05321A799714AADE8",
"codCampaign": "1",
"Telephone": "551199999999",
"Date": "2018-05-17 19:38:26",
"status": "read",
"type": "WhatsappStatus"
}
Uma listagem de erros que podem ser retornados da API.
Ao realizar um POST com um JSON valido na API, o retorno será 200 contendo o Json de retorno do POST no Body. Em caso de Json inválido, a API vai retornar Status 400 (Bad Resquest) e no Body informar qual o possível erro do JSon, segue abaixo lista de erros e orientações para o mesmo.
| Cod.Erro | Erro | Orientação |
|---|---|---|
| 1 | Invalid transference format | Json fora do formato especificado na documentação, verifique o exemplo. |
| 2 | Login not found | Login não encontrado, verifiquei o Login informado ou entre em contato com a Flex. |
| 3 | Invalid password | Password invalido, verifiquei o Login informado ou entre em contato com a Flex. |
| 4 | Invalid Token | Token informado é invalido ou já foi renovado, informe o token atual ou refaça o Login. |
| 5 | Expired Token | Token informado expirou e é necessário nova validação no Login. |
| 6 | Enter the Token field | Informe o Token obtido no Login dentro da assinatura Json. |
| 7 | Please report a valid campaign | Campanha atual informada não existe, verifique. |
| 8 | Please report a valid date | Campanha atual informada não existe, verifique. |
| 10 | Please report a valid Id | ID no formato invalido. |
| 11 | Description of (Lote) already registered. | Descrição do lote informado não esta registrado (Erro disponível somente para API MAIL). |
| 12 | Description of (html_pach) already registered. | Descrição do template informado não esta registrado (Erro disponível somente para API MAIL). |
| 13 | Please report a valid namespace | Namespace informada não existe, verifique. (Erro disponível somente para API MENSAGERIA - WHATSAPP). |
| 14 | Number of fields reported differently than expected for codNamespace | Numero de fields informado, esta diferente do numero esperado pelo Namespace. |
| 16 | Please report a valid IdMedia | IdMedia invalido ou não cadastrado no Upload. |
| 17 | Please report a valid NEW campaign | Nova campanha informada não existe, verifique. |
| 18 | Informed campaign does not belong to a Whatsapp campaign | Campanha atual informada não pertence a uma campanha Whatsapp, somente é possível transferir entre campanhas de Whatsapp. |
| 19 | NEW Campaign reported does not belong to a Whatsapp campaign | Nova Campanha informada não pertence a uma campanha Whatsapp, somente é possível transferir entre campanhas de Whatsapp. |
| 20 | NEW Campaign with no registered callback url | Nova campanha não tem Url de callback cadastrada. |
| 21 | Information not found on the number reported for transfer. | Número de telefone informada não existe para a campanha atual.. |
| 22 | Campaign download canceled due to error in new campaign webhook. | Não foi possível concluir a transferência devido a problemas no webhook ao receber o histórico. |
| 24 | Invalid destination | Destino de operação e Chat não informado (Erro disponível somente para envio de CHAT sem Whatsapp). |
| 25 | Destination without registered URL | Destino de operação e Chat não cadastrado (Erro disponível somente para envio de CHAT sem Whatsapp). |
| 26 | Total sum of fields + phrase cannot be greater than the HSM limit of 1600 characters | Limite maximo de 1600 caracteres em mensagem HSM delimitados pelo Whatsapp. |
| 27 | Exclusive messages with hashCodeID, can only be sent 1 at a time in POST. | Mensagens expressas não podem ser enviadas em lote, somente uma por vez. |
| 28 | HashCodeID not found or expired | Id de Mensagem expressa não encontrado ou inválido. |