# 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.](https://docs.dchat.com.br/books/token-de-api "Token de API") Depois de obtido um token basta inserir no cabeçalho de suas requisições: ``` Authorization: Bearer ``` # 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.** [![Imagem do WhatsApp de 2025-02-04 à(s) 10.49.38_02b0c02e.jpg](https://docs.dchat.com.br/uploads/images/gallery/2025-02/scaled-1680-/nwsquKAGoHsgfypC-imagem-do-whatsapp-de-2025-02-04-as-10-49-38-02b0c02e.jpg)](https://docs.dchat.com.br/uploads/images/gallery/2025-02/nwsquKAGoHsgfypC-imagem-do-whatsapp-de-2025-02-04-as-10-49-38-02b0c02e.jpg) Sua estrutura na requisição deverá ser: ```json { "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. [![Imagem do WhatsApp de 2025-02-04 à(s) 11.09.04_47d4c2e1.jpg](https://docs.dchat.com.br/uploads/images/gallery/2025-02/scaled-1680-/55JJvemAEzYqf9vZ-imagem-do-whatsapp-de-2025-02-04-as-11-09-04-47d4c2e1.jpg)](https://docs.dchat.com.br/uploads/images/gallery/2025-02/55JJvemAEzYqf9vZ-imagem-do-whatsapp-de-2025-02-04-as-11-09-04-47d4c2e1.jpg) Sua estrutura na requisição deverá ser: ```json { "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. [![Imagem do WhatsApp de 2025-02-04 à(s) 11.08.06_fe06d208.jpg](https://docs.dchat.com.br/uploads/images/gallery/2025-02/scaled-1680-/IGU7dh7OV8vaiBLn-imagem-do-whatsapp-de-2025-02-04-as-11-08-06-fe06d208.jpg)](https://docs.dchat.com.br/uploads/images/gallery/2025-02/IGU7dh7OV8vaiBLn-imagem-do-whatsapp-de-2025-02-04-as-11-08-06-fe06d208.jpg) Sua estrutura na requisição deverá ser: ```json { "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. [![Imagem do WhatsApp de 2025-02-04 à(s) 11.12.40_a8cf6ada.jpg](https://docs.dchat.com.br/uploads/images/gallery/2025-02/scaled-1680-/kAB96waUKNGmPe9g-imagem-do-whatsapp-de-2025-02-04-as-11-12-40-a8cf6ada.jpg)](https://docs.dchat.com.br/uploads/images/gallery/2025-02/kAB96waUKNGmPe9g-imagem-do-whatsapp-de-2025-02-04-as-11-12-40-a8cf6ada.jpg) Sua estrutura na requisição deverá ser: ```json { "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](https://docs.dchat.com.br/books/rcs-api/page/botoes "Botões"). O limite da mensagem é de **dois mil caracteres**. Sua estrutura na requisição deverá ser: ```json { "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é ](https://docs.dchat.com.br/books/rcs-api/page/botoes "Botões")**[4 botões](https://docs.dchat.com.br/books/rcs-api/page/botoes "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). [![Imagem do WhatsApp de 2025-02-04 à(s) 14.48.00_2d87a939.jpg](https://docs.dchat.com.br/uploads/images/gallery/2025-02/scaled-1680-/rY5D5Rpdy8vFGHVg-imagem-do-whatsapp-de-2025-02-04-as-14-48-00-2d87a939.jpg)](https://docs.dchat.com.br/uploads/images/gallery/2025-02/rY5D5Rpdy8vFGHVg-imagem-do-whatsapp-de-2025-02-04-as-14-48-00-2d87a939.jpg) [![image.png](https://docs.dchat.com.br/uploads/images/gallery/2025-02/scaled-1680-/QYOjP9ZjVNNEnNjZ-image.png)](https://docs.dchat.com.br/uploads/images/gallery/2025-02/QYOjP9ZjVNNEnNjZ-image.png) Sua estrutura na requisição deverá ser: ```json { "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: 1. Link 2. Reply 3. 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://

[![image.png](https://docs.dchat.com.br/uploads/images/gallery/2025-02/scaled-1680-/4phLZlzddSMOFD5W-image.png)](https://docs.dchat.com.br/uploads/images/gallery/2025-02/4phLZlzddSMOFD5W-image.png) Sua estrutura é: ```json { "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!

[![image.png](https://docs.dchat.com.br/uploads/images/gallery/2025-02/scaled-1680-/qpPpAfji9bkf1XiS-image.png)](https://docs.dchat.com.br/uploads/images/gallery/2025-02/qpPpAfji9bkf1XiS-image.png) Sua estrutura é: ```json { "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`.

[![image.png](https://docs.dchat.com.br/uploads/images/gallery/2025-02/scaled-1680-/uTgPcusMA0qTkmww-image.png)](https://docs.dchat.com.br/uploads/images/gallery/2025-02/uTgPcusMA0qTkmww-image.png) Sua estrutura é: ```json { "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](https://docs.dchat.com.br/books/rcs-api/page/autenticacao "Autenticação"). #### 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.](https://docs.dchat.com.br/books/rcs-api/chapter/tipos-de-mensagens "Tipos de Mensagens") ##### 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. ```json { "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. ```json { "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.](https://docs.dchat.com.br/books/rcs-api/page/respostas-de-erro "Respostas de erro") ```json { "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: ```json { "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: ```json { "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).](https://docs.dchat.com.br/books/rcs-api/page/disparando-um-rcs#bkmrk-c%C3%B3digo-do-disparo) #### Atualização de Status da Mensagem ##### Mensagem Entregue ```json { "batch": "41", "token": "5514999998877", "status": "delivered", "message": "", } ``` ##### Mensagem Lida ```json { "batch": "41", "token": "5514999998877", "status": "read", "message": "", } ``` ##### Erro ```json { "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**. ```json { "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. ```json { "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.

```json { "batch": "41", "token": "5514999998877", "status": "sms_sent", "message": "", } ``` ##### SMS Entregue ```json { "batch": "41", "token": "5514999998877", "status": "sms_delivered", "message": "", } ``` #### Respostas ```json { "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 ```json { "batch": "36", "token": "5514999998877", "type": "response", "text": "Liga pra mim!", "data": "5514981546757" } ``` ##### Link ```json { "batch": "36", "token": "5514999998877", "type": "response", "text": "Acesse nosso site!", "data": "https://dfive.com.br" } ```