API Witime RCS — Guía de integración

Objetivo

Este documento describe exclusivamente el contrato público de la API Witime RCS. Incluye autenticación, formatos de datos, respuestas, errores y ejemplos de integración para todos los endpoints disponibles para el cliente.

Información general

URL base

Sustituya https://rcs-api.witi.me en los ejemplos por la URL proporcionada para su entorno.

https://rcs-api.witi.me

Formato de los datos

Las solicitudes y respuestas usan JSON con nombres de propiedades en camelCase.

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

Autenticación

Todas las solicitudes requieren el encabezado X-Api-Key:

X-Api-Key: TU_CLAVE_DE_ACCESO

Una clave ausente o no válida devuelve 401 Unauthorized:

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

Correlación

El encabezado X-Correlation-Id es opcional. Si se proporciona, se devuelve el mismo valor en la respuesta. Si se omite, la API genera un identificador con el formato corr_<guid>.

X-Correlation-Id: pedido-2026-0001

Idempotencia

Las solicitudes de envío de mensajes y plantillas admiten el encabezado opcional Idempotency-Key.

Idempotency-Key: envio-2026-0001

Reintentar la misma solicitud con la misma clave y el mismo contenido devuelve la respuesta original. Reutilizar la clave con contenido diferente devuelve 409 Conflict:

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

Validación del cuerpo de la solicitud

Las solicitudes GET no incluyen cuerpo. En las solicitudes POST, un cuerpo vacío devuelve 400 Bad Request con el código EMPTY_BODY. El JSON mal formado devuelve:

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

Configuración común para los ejemplos de C#

Los ejemplos de C# usan HttpClient y System.Net.Http.Json. Suponga que estas variables están disponibles en cada ejemplo:

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

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

---

1. Comprobar disponibilidad

Comprueba si la API está respondiendo. Esta solicitud no prueba ningún servicio adicional.

GET /health

cURL

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

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);

Respuesta 200 OK

{
  "status": "ok"
}

---

2. Enviar un mensaje

Envía un mensaje a uno o varios destinatarios.

POST /v1/messages

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
senderProfileId	string	Sí	Identificador del perfil remitente.
route	int	Sí	ID de la ruta que se utilizará.
campaignName	string	No	Nombre de la campaña.
channel	string	Sí	Canal solicitado: rcs o sms.
message	object	Sí	Contenido del mensaje. No es obligatorio si se indica el campo template.
template	int	No	Plantilla RCS preconfigurada.
recipients	array	Sí	Lista con al menos un destinatario.

Cada destinatario contiene:

Campo	Tipo	Obligatorio	Descripción
phone	string	Sí	Número de teléfono con código de país y prefijo de área.

Tipos de contenido admitidos

message.type	Campos utilizados
text	text
image	url
video	url y text opcional
pdf	url y filename opcional
suggestion	text y suggestions
rich-card	title, description, url, orientation, alignment y suggestions
carousel	cards; cada tarjeta contiene los campos de rich-card

Una sugerencia admite title, value, type y campos opcionales de visualización, ubicación y calendario. Tipos admitidos: openurl, openurlwebview, call, reply, viewlocationaction, sharelocationaction y createcalendareventaction.

Ejemplo de solicitud

{
  "route": 123,
	"campaignName": "bienvenida-2026",
  "senderProfileId": "snd_default",
  "channel": "rcs",
  "message": {
	"type": "text",
	"text": "¡Hola! Tu registro se ha completado."
  },
  "recipients": [
	{
	  "phone": "5511999999999"
	}
  ]
}

cURL

curl -X POST "https://rcs-api.witi.me/v1/messages" \
	-H "X-Api-Key: TU_CLAVE_DE_ACCESO" \
	-H "X-Correlation-Id: pedido-2026-0001" \
	-H "Idempotency-Key: envio-2026-0001" \
  -H "Content-Type: application/json" \
  --data '{
	"route": 123,
	"campaignName": "bienvenida-2026",
	"senderProfileId": "snd_default",
	"channel": "rcs",
	"message": {
	  "type": "text",
	"text": "¡Hola! Tu registro se ha completado."
	},
	"recipients": [
	  {
		"phone": "5511999999999"
	  }
	]
  }'

C#

var payload = new
{
	route = 123,
	campaignName = "bienvenida-2026",
	senderProfileId = "snd_default",
	channel = "rcs",
	message = new
	{
		type = "text",
		text = "¡Hola! Tu registro se ha completado."
	},
	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);

Respuesta 200 OK

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

Posibles errores de validación: INVALID_ACCOUNT, INVALID_APIKEY, INVALID_BASEURL, INVALID_RECIPIENTS e INVALID_MESSAGE.

---

3. Consultar un mensaje

Consulta un mensaje mediante el identificador devuelto al enviarlo.

GET /v1/messages/{messageId}

cURL

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

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);

Respuesta 200 OK

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

Devuelve 404 Not Found si el identificador no existe.

---

4. Listar plantillas

Devuelve las plantillas disponibles para la cuenta.

GET /v1/templates

cURL

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

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);

Respuesta 200 OK

[
  {
	"templateId": "tpl_01",
	"name": "Bienvenida"
  }
]

5. Consultar una plantilla

Consulta una plantilla mediante su identificador.

GET /v1/templates/{templateId}

cURL

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

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);

Respuesta 200 OK

{
  "templateId": "tpl_01",
	"name": "Bienvenida"
}

Devuelve 404 Not Found si el identificador no existe.

Códigos de estado HTTP

Código	Significado
200	Solicitud procesada.
400	Cuerpo vacío, JSON no válido o datos obligatorios no válidos.
401	Clave de acceso ausente o no válida.
404	No se encontró el mensaje o la plantilla.
409	Se reutilizó la clave de idempotencia con contenido diferente.
500	Error inesperado durante el procesamiento.

Recomendaciones de integración

• Mantenga la clave de acceso fuera del código fuente.
• Genere una Idempotency-Key única para cada operación lógica de envío.
• Registre el X-Correlation-Id recibido en la respuesta.
• Guarde los valores batchId y messageId devueltos.
• Gestione las respuestas que no sean 2xx antes de deserializar el resultado esperado.
• Aplique tiempos de espera y cancelación a las solicitudes HTTP.
• No dependa del orden de las propiedades JSON.
• Envíe los números de teléfono en formato internacional y solo con dígitos.