RCS Api
Documentações para a API RCS.
Autenticação
Toda requisição feita para a API do dChat deve conter em seu cabeçalho HTTP um Token de API. Se você ainda não possui um ou não sabe como utilizá-lo, recomendamos a leitura da documentação Token de API.
Depois de obtido um token basta inserir no cabeçalho de suas requisições:
Authorization: Bearer <token>Tipos de Mensagens
Texto
A mensagem de Texto é o tipo de mensagem mais simples do RCS. Muito semelhante ao SMS tradicional.
Sua principal diferença é seu tamanho, que ao invés dos 160 caracteres do SMS, tem um limite de 5.000 caracteres.
Sua estrutura na requisição deverá ser:
{
"text": {
"message": "Mensagem com limite de 5000 caracteres."
}
}
Imagem
- A mensagem de Imagem permite o envio de uma imagem nos formatos .gif, .jpg ou .png e tamanho máximo de 2MB.
- A resolução ideal para imagens é de 500px por 300px.
- É recomendável deixar a imagem centralizada com uma margem lateral de 100px.
Sua estrutura na requisição deverá ser:
{
"image": {
"url": "https://seusite.com/imagem.png"
}
}Vídeo
- A mensagem de Vídeo permite o envio de um vídeo no mp4.
- O tamanho máximo deve ser de até 50MB.
Sua estrutura na requisição deverá ser:
{
"video": {
"url": "https://seusite.com/video.mp4"
}
}Documento (PDF)
- A mensagem de Documento permite o envio de um arquivo no formato PDF.
- O tamanho máximo deve ser de 2MB.
Sua estrutura na requisição deverá ser:
{
"pdf": {
"url": "https://seusite.com/document.pdf"
}
}Sugestões
O tipo de mensagem Sugestão assemelha-se à uma mensagem de texto convencional, mas tem como diferencial a possibilidade de se adicionar até quatro botões de ação rápida.
O limite da mensagem é de dois mil caracteres.
Sua estrutura na requisição deverá ser:
{
"suggestion":{
"text":"Texto da mensagem!",
"suggestions":[
{
"type":"link",
"title":"Abrir o dChat",
"value":"https://sistema.dchat.com.br"
},
{
"type":"link",
"title":"Visite nosso site",
"value":"https://dfive.com.br"
},
{
"type":"reply",
"title":"Parar de Receber",
"value":"Sair"
},
{
"type":"call",
"title":"Ligar",
"value":"5511999998877"
}
]
}
}Cards
Na opção Card, você combina a comunicação por texto, onde pode enviar mensagens com caracteres especiais, acentos, variáveis e emojis, com a comunicação por imagens, ideal para captar a atenção do seu cliente. Além disso, você pode adicionar até 4 botões.
O limite da mensagem é de dois mil caracteres.
Os arquivos suportados devem estar em formato .gif, .jpg e .png com no máximo 2MB e .mp4 com no máximo 10MB (resolução ideal: 500x300px com borda de até 100x100px).
Sua estrutura na requisição deverá ser:
{
"title":"Dfive Consultoria",
"description":"Oferecemos soluções inovadoras em atendimento e comunicação desde 2019, aprimorando o relacionamento entre empresas e clientes com eficiência e tecnologia de ponta.",
"suggestions":[
{
"title":"Fale conosco",
"type":"link",
"value":"http:/wa.me/1338777102"
},
{
"title":"Ligar agora",
"type":"call",
"value":"1338777102"
}
],
"fileUrl":"https:/sistema.dchat.com.b/storage/rcs-template/1/carousel-3.png"
},Botões
No RCS, existem três tipos de botões para envio via API:
- Link
- Reply
- Call
A estrutura para todos seguem o mesmo padrão contendo o type, que determina o tipo do botão, o title que será o texto do botão (deve conter até 25 caracteres) e o value com o valor do botão.
Link
O botão link abre o navegador com a URL especificada.
Não esqueça que é obrigatório o protocolo, por exemplo https://
Sua estrutura é:
{
"type":"link",
"title":"Visite nosso site",
"value":"https://dfive.com.br"
}Reply
O botão do tipo reply responde o RCS com um SMS contendo o valor da propriedade value. Ele é interessante em opções como o sair de uma lista, ou a confirmação de uma ação.
A cobrança da resposta é feita em sua conta e não do cliente!
Sua estrutura é:
{
"type":"reply",
"title":"Título do botão",
"value":"Resposta que será enviada por SMS"
}Call
O botão do tipo call abre o discador com o número definido em value já preenchido.
Atente-se que se a mensagem for enviada pra um número internacional, você deve incluir o código DDI, por exemplo o +55, no value.
Sua estrutura é:
{
"type":"call",
"title":"Título do botão",
"value":"+5514999998877"
}Disparando um RCS
Endpoint
Para enviar uma campanha RCS, você deve fazer uma requisição do tipo POST para o endpoint https://sistema.dchat.com.br/api/rcs/send .
Autenticação
Você deve adicionar ao cabeçalho da requisição a sua API Token, através do cabeçalho Authorization. Se você ainda não possui sua chave, veja aqui como criar uma.
Corpo da Requisição
O body da sua requisição deve ser no formato JSON contendo obrigatoriamente os campos fallback, callback, messages e tokens, mas fique tranquilo que falaremos deles a seguir.
fallback
O campo fallback é do tipo boolean, ou seja, deve conter os valores true ou false. Ele serve para identificar se devemos enviar um SMS para aparelhos que não tenham suporte ao RCS.
Se você definir o fallback como false, o seu crédito será ressarcido assim que for verificado que o número não possuir suporte ao RCS.
fallback_message
O campo fallback_message determina qual será o SMS enviado caso o campo fallback seja true. O tamanho máximo desse campo segue o limite de um SMS, ou seja, 160 caracteres.
É importante lembrar, que apesar do envio ser um SMS, ele é cobrado como um RCS.
callback
Serve para identificar para o servidor qual a URL que deverá receber as notificações de envio e respostas de cada token.
messages
É um array de mensagens. Como existem vários tipos de mensagens e cada uma tem sua particularidade, elas foram tratadas em um capítulo separado.
tokens
É um array de strings contendo os números que irão receber os RCS. O token pode ou não conter o DDI, caso ele não seja informado incluiremos o do Brasil por padrão.
Lembre-se sempre de enviar os tokens entre aspas (").
Exemplo de requisição
No exemplo a seguir, seriam enviadas três mensagens, uma contendo uma imagem, a outra um vídeo e por último um PDF, para três números de celulares.
{
"fallback": false,
"callback": "https://localhost/rcs-callback",
"messages": [
{
"image": {
"url": "http://localhost/images/thechat_logo.png"
}
},
{
"video": {
"url": "https://file-examples.com/wp-content/storage/2017/04/file_example_MP4_480_1_5MG.mp4"
}
},
{
"pdf": {
"url": "https://file-examples.com/wp-content/storage/2017/10/file-sample_150kB.pdf"
}
}
],
"tokens": [
"14981546797",
"11632359235",
"13981654572"
]
}Um outro exemplo com o envio de um Card com quatro botões e com fallback ativo.
{
"fallback": true,
"fallback_message": "Você ainda não possui suporte ao RCS!",
"callback": "https://localhost",
"messages": [
{
"card": {
"text": "Mensagem de Texto",
"title": "Título do Card!",
"url": "http://localhost/images/thechat_logo.png",
"options": [
{
"type": "call",
"title": "Liga pra mim!",
"value": "14981546757"
},
{
"type": "call",
"title": "Acesse nosso insta",
"value": "https://instagram.com/ricocrivelli"
},
{
"type": "reply",
"title": "Parar de receber mensagem",
"value": "Sair"
},
{
"type": "link",
"title": "Acesse nosso site!",
"value": "https://uol.com.br"
},
{
"type": "call",
"title": "Ignorado",
"value": "Nao vai computador"
}
]
}
}
],
"tokens": [
"14981546757",
"14632359235",
"14981654572"
]
}Retorno da requisição
A requisição irá retornar uma resposta no formato JSON indicando se houve erro e qual foi ou se o envio foi um sucesso, além do código do disparo.
As mensagens de erro estão em um capítulo separado.
{
"success": true,
"batch": 1
}Código do Disparo
O código do disparo (parâmetro batch) é um número único e que será enviado sempre junto com as respostas de callback, portanto é necessário sempre guardar essa informação, para que junto com o número de celular, torne os tokens únicos.
Respostas de erro
O servidor poderá responder com duas mensagens de erro. O status da requisição será sempre 403.
O usuário não possui acesso ao módulo RCS
Caso o usuário não tenha permissão para enviar um RCS, a seguinte mensagem será retornada:
{
"success": false,
"error": "You don't have access to this module.",
"code": "RCS001"
}O usuário não possui créditos suficientes
Caso o usuário não tenha créditos suficientes a seguinte mensagem será retornada:
{
"success": false,
"error": "You don't have enough credits.",
"code": "RCS002"
}
Chamadas de Callback
Sempre que você fornecer uma URL no parâmetro callback_url e houver alguma atualização, uma requisição será enviada para o endereço. O corpo da requisição depende to tipo da atualização, mas sempre contará com o código do envio (parâmetro batch).
Atualização de Status da Mensagem
Mensagem Entregue
{
"batch": "41",
"token": "5514999998877",
"status": "delivered",
"message": "",
}Mensagem Lida
{
"batch": "41",
"token": "5514999998877",
"status": "read",
"message": "",
}Erro
{
"batch": "41",
"token": "5514999998877",
"status": "exception",
"message": "Aparelho não possui suporte ao RCS.",
}Expirado
Quando o RCS não consegue ser entregue em 24 horas ele é automaticamente descartado pelo Google e o saldo ressarcido.
{
"batch": "41",
"token": "5514999998877",
"status": "expired",
"message": "",
}Duplicidade
Para evitar o envio de SPAM, você não pode enviar dois ou mais RCS para o mesmo número com conteúdo semelhante em um período de três horas.
{
"batch": "41",
"token": "5514999998877",
"status": "error",
"message": "Bloqueado por duplicidade.",
}SMS de Fallback
Se você optar por enviar um SMS para os números que não possuírem suporte ao RCS você poderá receber dois tipos de requisições.
SMS Enviado
Atenção: Algumas operadoras não informam a entrega do SMS, então um "SMS Enviado" pode ter sido entregue ou não.
{
"batch": "41",
"token": "5514999998877",
"status": "sms_sent",
"message": "",
}SMS Entregue
{
"batch": "41",
"token": "5514999998877",
"status": "sms_delivered",
"message": "",
}Respostas
{
"batch": "36",
"token": "5514999998877",
"type": "reply",
"message": "Texto da mensagem"
}Call e Link
Os botões do tipo call e link retornam da mesma forma.
Call
{
"batch": "36",
"token": "5514999998877",
"type": "response",
"text": "Liga pra mim!",
"data": "5514981546757"
}Link
{
"batch": "36",
"token": "5514999998877",
"type": "response",
"text": "Acesse nosso site!",
"data": "https://dfive.com.br"
}