FacilitaMessaging
Documentação da API RCS v1
Abrir conta Painel RCS Coleção de exemplos

Primeiros Passos

RCS (Rich Communication Services) e a evolucao do SMS, permitindo mensagens interativas com midia, botoes e cards em uma experiencia mais rica para o cliente.

Para integrar com a API da Facilita RCS, voce precisa gerar sua chave de integracao (hashSeguranca) diretamente no painel da plataforma.

Para criar conta ou adquirir creditos, acesse: https://www.facilitamovel.com.br/

Para acessar o painel RCS, acesse: https://rcs.facilitamovel.com.br/login

Fluxo recomendado: faca login no painel Facilita RCS, abra o menu Integracao e clique em Gerar chave. Depois, use essa chave no header hashSeguranca das requisicoes.

+---------------------------+
| 1) Login no Facilita RCS |
+---------------------------+
              |
              v
+---------------------------+
| 2) Menu lateral           |
|    -> Integracao          |
+---------------------------+
              |
              v
+---------------------------+
| 3) Tela Integracao        |
|    -> Botao "Gerar chave" |
+---------------------------+
              |
              v
+---------------------------+
| 4) Copiar hashSeguranca   |
|    (mostrada so 1 vez)    |
+---------------------------+

Creditos RCS e SMS

Consulte os dois saldos e a validade do SMS pela API com GET /rcs/integration/credits, enviando o mesmo header hashSeguranca. A requisicao nao possui body.

{
  "success": true,
  "usuarioId": 123,
  "clienteId": 45,
  "creditosRcs": 2500,
  "creditosRcsValidos": true,
  "creditosSms": 800,
  "expiracaoCreditosSms": "2026-12-31T23:59:59",
  "creditosSmsExpirados": false,
  "creditosSmsValidos": true,
  "consultadoEm": "2026-10-19T14:30:00"
}

RCS nao expira: creditosRcsValidos depende somente de saldo positivo. A validade pertence ao SMS; quando expiracaoCreditosSms for nula, nao ha expiracao cadastrada. creditosSmsValidos exige saldo positivo e validade nao expirada.

Fallback para SMS

O fallback nao envia RCS e SMS ao mesmo tempo. A plataforma tenta entregar o RCS primeiro e envia o SMS somente aos destinatarios para os quais o RCS falhar, desde que exista saldo SMS valido.

Os campos enableSMSFallback e conteudoSmsFallback sao opcionais em todos os endpoints. Integracoes existentes continuam funcionando sem qualquer alteracao.

{
  "campaignName": "Campanha com fallback",
  "recipients": [
    { "phone": "5511999999999" }
  ],
  "message": "Mensagem principal enviada por RCS",
  "enableSMSFallback": true,
  "conteudoSmsFallback": "Nao foi possivel entregar o RCS. Acesse https://exemplo.com"
}

Quando ativado, o conteudo do SMS e obrigatorio, aceita ate 160 caracteres e exige creditos SMS com validade vigente. O saldo e consumido apenas se o fallback for efetivamente enviado.

Com webhook configurado, o envio do fallback gera o status FALLBACK_SMS_SENT com o identificador data.smsId.

Webhooks de retorno

No menu Integracao, cadastre uma URL HTTPS publica e gere o segredo de assinatura. Opcionalmente, envie callbackUrl no body para substituir a URL somente naquela campanha.

Exemplo de envio com callback no JSON:

{
  "campaignName": "Campanha com webhook",
  "recipients": [
    {
      "phone": "5511999999999",
      "externalId": "cobranca-12345"
    }
  ],
  "message": "Teste de retorno por webhook",
  "callbackUrl": "https://api.seudominio.com/webhooks/facilita-rcs"
}

Prioridade: callbackUrl do JSON; quando ausente, URL padrao ativa do painel; quando nenhuma estiver disponivel, nenhum webhook e gerado.

Eventos publicados: message.status, message.click e message.response.

{
  "eventId": "3ca11a60-6cc8-4a99-a704-7c7e703fcdec",
  "eventType": "message.status",
  "version": "1.0",
  "occurredAt": "2026-10-13T15:03:25",
  "campaignId": 5766,
  "messageId": 987654,
  "externalId": "cobranca-12345",
  "phone": "11999999999",
  "data": {
    "status": "DELIVERED",
    "deliveredWithConfirmation": true
  }
}

Headers: X-Facilita-Event-Id, X-Facilita-Timestamp e X-Facilita-Signature. A assinatura e HMAC-SHA256(segredo, timestamp + "." + corpo original).

Responda com HTTP 2xx em ate 5 segundos. A entrega e feita pelo menos uma vez; deduplique pelo eventId. Em caso de falha, ha novas tentativas em 1 min, 5 min, 15 min, 1 h, 6 h e 24 h.

O painel de Integracao mostra os logs e cada tentativa. Com 3 falhas consecutivas o webhook aparece como instavel; com 10 falhas ele e desativado automaticamente. Uma entrega bem-sucedida zera o contador. Os logs finalizados ficam disponiveis por 14 dias.

A protecao automatica se aplica a URL padrao. Uma callbackUrl especifica de campanha segue suas proprias tentativas sem desativar a URL padrao do cliente.

Na desativacao, a Facilita envia um unico aviso aos e-mails validos cadastrados em resp_email, inclusive varios enderecos separados por virgula. Valores contendo nao enviar, naoenviar ou não enviar sao ignorados.

Contato comercial - Facilita Movel

Rua Luciana de Abreu 337 Sala 501

CEP 90570-060

Porto Alegre - RS

Telefone: (51) 3209-0558

WhatsApp: (51) 9-9939 3911 (chamar direto)

E-mail: comercial@facilitamovel.com.br

POST
/rcs/integration/send/text
RequestPOST /text
TipoTexto
OrigemIntegracao API
Limite destinatarios1 a 2000
Header Obrigatorio Observacao
hashSeguranca Sim Chave de Integracao em formato MD5.
  • Sem hashSeguranca ou hash invalido: 401
  • API desabilitada, usuario inativo, RCS sem saldo ou fallback sem SMS valido: 403
hashSeguranca: seu_hash_de_integracao
Status Cenario Exemplo
Campo Regra
Regras aplicadas automaticamente pela API antes de processar o envio.