API Witime RCS — Guia de integração

Objetivo

Este documento descreve exclusivamente o contrato público da API Witime RCS. Ele contém autenticação, formatos de dados, respostas, erros e exemplos de integração para todas as chamadas disponíveis ao cliente.

Informações gerais

URL base

Substitua https://rcs-api.witi.me nos exemplos pela URL fornecida para o seu ambiente.

https://rcs-api.witi.me

Formato dos dados

Requests e responses usam JSON com nomes de propriedades em camelCase.

Content-Type: application/json
Accept: application/json

Autenticação

Todas as chamadas exigem o header X-Api-Key:

X-Api-Key: SUA_CHAVE_DE_ACESSO

Uma chave ausente ou inválida retorna 401 Unauthorized:

{
  "error": {
	"code": "AUTHENTICATION_FAILED",
	"message": "Invalid API key."
  }
}

Correlação

O header X-Correlation-Id é opcional. Quando informado, o mesmo valor é devolvido na resposta. Quando omitido, a API gera um identificador no formato corr_<guid>.

X-Correlation-Id: pedido-2026-0001

Idempotência

As chamadas de envio de mensagem e envio de template aceitam o header opcional Idempotency-Key.

Idempotency-Key: envio-2026-0001

O reenvio da mesma chamada, com a mesma chave e o mesmo conteúdo, devolve a resposta original. Reutilizar a chave com conteúdo diferente retorna 409 Conflict:

{
  "error": {
	"code": "DUPLICATE_IDEMPOTENCY_KEY",
	"message": "A different request was already sent with the same Idempotency-Key."
  }
}

Validação do body

Chamadas GET não enviam body. Nas chamadas POST, um body vazio retorna 400 Bad Request com o código EMPTY_BODY. JSON malformado retorna:

{
  "error": {
	"code": "INVALID_JSON",
	"message": "Request body contains invalid JSON."
  }
}

Configuração comum dos exemplos C#

Os exemplos C# usam HttpClient e System.Net.Http.Json. Considere estas variáveis disponíveis em cada exemplo:

using System.Net.Http.Json;
using System.Text;
using System.Text.Json;

var baseUrl = "https://rcs-api.witi.me";
var apiKey = "SUA_CHAVE_DE_ACESSO";
using var client = new HttpClient();

---

1. Verificar disponibilidade

Verifica se a API está respondendo. Esta chamada não testa serviços adicionais.

GET /health

cURL

curl -X GET "https://rcs-api.witi.me/health" \
	-H "X-Api-Key: SUA_CHAVE_DE_ACESSO"

C#

using var request = new HttpRequestMessage(HttpMethod.Get, $"{baseUrl}/health");
request.Headers.Add("X-Api-Key", apiKey);

using var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(responseBody);

Response 200 OK

{
  "status": "ok"
}

---

2. Enviar mensagem

Envia uma mensagem para um ou mais destinatários.

POST /v1/messages

Campos do request

Campo	Tipo	Obrigatório	Descrição
senderProfileId	string	Sim	Identificador do perfil remetente.
route	int	Sim	Id da rota a ser utilizada.
campaignName	string	Não	Nome da campanha.
channel	string	Sim	Canal solicitado: rcs ou sms.
message	object	Sim	Conteúdo da mensagem. (Não obrigatório se informado o campo 'template')
template	int	Não	Template RCS pré-cadastrado.
recipients	array	Sim	Lista com pelo menos um destinatário.

Cada destinatário contém:

Campo	Tipo	Obrigatório	Descrição
phone	string	Sim	Telefone com código do país e DDD.

Conteúdos aceitos

message.type	Campos utilizados
text	text
image	url
video	url e text opcional
pdf	url e filename opcional
suggestion	text e suggestions
rich-card	title, description, url, orientation, alignment e suggestions
carousel	cards, cada card com os campos de rich-card

Uma sugestão aceita title, value, type e campos opcionais de visualização, localização e calendário. Tipos aceitos: openurl, openurlwebview, call, reply, viewlocationaction, sharelocationaction e createcalendareventaction.

Request de exemplo

{
  "route": 123,
  "campaignName": "boas-vindas-2026",
  "senderProfileId": "snd_default",
  "channel": "rcs",
  "message": {
	"type": "text",
	"text": "Olá! Seu cadastro foi concluído."
  },
  "recipients": [
	{
	  "phone": "5511999999999"
	}
  ]
}

cURL

curl -X POST "https://rcs-api.witi.me/v1/messages" \
  -H "X-Api-Key: SUA_CHAVE_DE_ACESSO" \
  -H "X-Correlation-Id: pedido-2026-0001" \
  -H "Idempotency-Key: envio-2026-0001" \
  -H "Content-Type: application/json" \
  --data '{
	"route": 123,
	"campaignName": "boas-vindas-2026",
	"senderProfileId": "snd_default",
	"channel": "rcs",
	"message": {
	  "type": "text",
	  "text": "Olá! Seu cadastro foi concluído."
	},
	"recipients": [
	  {
		"phone": "5511999999999"
	  }
	]
  }'

C#

var payload = new
{
	route = 123,
	campaignName = "boas-vindas-2026",
	senderProfileId = "snd_default",
	channel = "rcs",
	message = new
	{
		type = "text",
		text = "Olá! Seu cadastro foi concluído."
	},
	recipients = new[]
	{
		new
		{
			phone = "5511999999999"
		}
	}
};

using var request = new HttpRequestMessage(HttpMethod.Post, $"{baseUrl}/v1/messages")
{
	Content = JsonContent.Create(payload)
};
request.Headers.Add("X-Api-Key", apiKey);
request.Headers.Add("X-Correlation-Id", "pedido-2026-0001");
request.Headers.Add("Idempotency-Key", "envio-2026-0001");

using var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(responseBody);

Response 200 OK

{
  "batchId": "batch_01",
  "status": "accepted",
  "messages": [
	{
	  "messageId": "msg_01",
	  "recipient": "5511999999999",
	  "status": "accepted"
	}
  ],
  "rejected": []
}

Possíveis validações: INVALID_ACCOUNT, INVALID_APIKEY, INVALID_BASEURL, INVALID_RECIPIENTS e INVALID_MESSAGE.

---

3. Consultar mensagem

Consulta uma mensagem pelo identificador retornado no envio.

GET /v1/messages/{messageId}

cURL

curl -X GET "https://rcs-api.witi.me/v1/messages/msg_01" \
	-H "X-Api-Key: SUA_CHAVE_DE_ACESSO"

C#

var messageId = "msg_01";
using var request = new HttpRequestMessage(HttpMethod.Get, $"{baseUrl}/v1/messages/{Uri.EscapeDataString(messageId)}");
request.Headers.Add("X-Api-Key", apiKey);

using var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(responseBody);

Response 200 OK

{
  "messageId": "msg_01",
  "status": 10,
  "recipient": "5511999999999",
  "deliverDate": "2026-09-24T10:21:47"
}

Retorna 404 Not Found quando o identificador não existe.

---

4. Listar templates

Retorna os templates disponíveis para a conta.

GET /v1/templates

cURL

curl -X GET "https://rcs-api.witi.me/v1/templates" \
	-H "X-Api-Key: SUA_CHAVE_DE_ACESSO"

C#

using var request = new HttpRequestMessage(HttpMethod.Get, $"{baseUrl}/v1/templates");
request.Headers.Add("X-Api-Key", apiKey);

using var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(responseBody);

Response 200 OK

[
  {
	"templateId": "tpl_01",
	"name": "Boas-vindas"
  }
]

5. Consultar template

Consulta um template criado pelo identificador.

GET /v1/templates/{templateId}

cURL

curl -X GET "https://rcs-api.witi.me/v1/templates/tpl_01" \
	-H "X-Api-Key: SUA_CHAVE_DE_ACESSO"

C#

var templateId = "tpl_01";
using var request = new HttpRequestMessage(HttpMethod.Get, $"{baseUrl}/v1/templates/{Uri.EscapeDataString(templateId)}");
request.Headers.Add("X-Api-Key", apiKey);

using var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(responseBody);

Response 200 OK

{
  "templateId": "tpl_01",
  "name": "Boas-vindas"
}

Retorna 404 Not Found quando o identificador não existe.

Códigos HTTP

Código	Significado
200	Chamada processada.
400	Body vazio, JSON inválido ou dados obrigatórios inválidos.
401	Chave de acesso ausente ou inválida.
404	Mensagem ou template não encontrado.
409	Chave de idempotência reutilizada com conteúdo diferente.
500	Erro inesperado no processamento.

Recomendações de integração

• mantenha a chave de acesso fora do código-fonte;
• gere uma Idempotency-Key única por operação lógica de envio;
• registre o X-Correlation-Id recebido na resposta;
• armazene batchId e messageId retornados;
• trate respostas não 2xx antes de desserializar o resultado esperado;
• aplique timeout e cancelamento nas chamadas HTTP;
• não dependa da ordem de propriedades JSON;
• envie telefones no formato internacional, somente com dígitos.