Witime RCS API — Integration Guide

Purpose

This document describes only the public contract of the Witime RCS API. It covers authentication, data formats, responses, errors, and integration examples for all client-facing endpoints.

General Information

Base URL

Replace https://rcs-api.witi.me in the examples with the URL provided for your environment.

https://rcs-api.witi.me

Data Format

Requests and responses use JSON with camelCase property names.

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

Authentication

All requests require the X-Api-Key header:

X-Api-Key: YOUR_ACCESS_KEY

A missing or invalid key returns 401 Unauthorized:

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

Correlation

The X-Correlation-Id header is optional. If provided, the same value is returned in the response. If omitted, the API generates an identifier in the format corr_<guid>.

X-Correlation-Id: order-2026-0001

Idempotency

Message-sending and template-sending requests accept the optional Idempotency-Key header.

Idempotency-Key: send-2026-0001

Retrying the same request with the same key and content returns the original response. Reusing the key with different content returns 409 Conflict:

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

Request Body Validation

GET requests do not include a body. For POST requests, an empty body returns 400 Bad Request with the code EMPTY_BODY. Malformed JSON returns:

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

Common Setup for C# Examples

The C# examples use HttpClient and System.Net.Http.Json. Assume these variables are available in each example:

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

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

1. Check Availability

Checks whether the API is responding. This request does not test any additional services.

GET /health

cURL

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

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. Send a Message

Sends a message to one or more recipients.

POST /v1/messages

Request Fields

Field	Type	Required	Description
`senderProfileId`	string	Yes	Sender profile identifier.
`route`	int	Yes	ID of the route to use.
`campaignName`	string	No	Campaign name.
`channel`	string	Yes	Requested channel: `rcs` or `sms`.
`message`	object	Yes	Message content. Not required when the `template` field is provided.
`template`	int	No	Preconfigured RCS template.
`recipients`	array	Yes	List containing at least one recipient.

Each recipient contains:

Field	Type	Required	Description
`phone`	string	Yes	Phone number with country code and area code.

Supported Content Types

`message.type`	Fields used
`text`	`text`
`image`	`url`
`video`	`url` and optional `text`
`pdf`	`url` and optional `filename`
`suggestion`	`text` and `suggestions`
`rich-card`	`title`, `description`, `url`, `orientation`, `alignment`, and `suggestions`
`carousel`	`cards`, each card containing the `rich-card` fields

A suggestion accepts title, value, type, and optional display, location, and calendar fields. Supported types: openurl, openurlwebview, call, reply, viewlocationaction, sharelocationaction, and createcalendareventaction.

Example Request

{
  "route": 123,
	"campaignName": "welcome-2026",
  "senderProfileId": "snd_default",
  "channel": "rcs",
  "message": {
	"type": "text",
	"text": "Hello! Your registration is complete."
  },
  "recipients": [
	{
	  "phone": "5511999999999"
	}
  ]
}

cURL

curl -X POST "https://rcs-api.witi.me/v1/messages" \
	-H "X-Api-Key: YOUR_ACCESS_KEY" \
	-H "X-Correlation-Id: order-2026-0001" \
	-H "Idempotency-Key: send-2026-0001" \
  -H "Content-Type: application/json" \
  --data '{
	"route": 123,
	"campaignName": "welcome-2026",
	"senderProfileId": "snd_default",
	"channel": "rcs",
	"message": {
	  "type": "text",
	"text": "Hello! Your registration is complete."
	},
	"recipients": [
	  {
		"phone": "5511999999999"
	  }
	]
  }'

C#

var payload = new
{
	route = 123,
	campaignName = "welcome-2026",
	senderProfileId = "snd_default",
	channel = "rcs",
	message = new
	{
		type = "text",
		text = "Hello! Your registration is complete."
	},
	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", "order-2026-0001");
request.Headers.Add("Idempotency-Key", "send-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": []
}

Possible validation errors: INVALID_ACCOUNT, INVALID_APIKEY, INVALID_BASEURL, INVALID_RECIPIENTS, and INVALID_MESSAGE.

3. Get a Message

Retrieves a message using the identifier returned when it was sent.

GET /v1/messages/{messageId}

cURL

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

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"
}

Returns 404 Not Found if the identifier does not exist.

4. List Templates

Returns the templates available to the account.

GET /v1/templates

cURL

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

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": "Welcome"
  }
]

5. Get a Template

Retrieves a template by its identifier.

GET /v1/templates/{templateId}

cURL

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

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": "Welcome"
}

Returns 404 Not Found if the identifier does not exist.

HTTP Status Codes

Code	Meaning
`200`	Request processed.
`400`	Empty body, invalid JSON, or invalid required data.
`401`	Missing or invalid access key.
`404`	Message or template not found.
`409`	Idempotency key reused with different content.
`500`	Unexpected processing error.

Integration Recommendations

Keep the access key out of source code.
Generate a unique Idempotency-Key for each logical send operation.
Log the X-Correlation-Id returned in the response.
Store the returned batchId and messageId values.
Handle non-2xx responses before deserializing the expected result.
Apply timeouts and cancellation to HTTP requests.
Do not rely on the order of JSON properties.
Send phone numbers in international format using digits only.

Purpose​

General Information​

Base URL​

Data Format​

Authentication​

Correlation​

Idempotency​

Request Body Validation​

Common Setup for C# Examples​

1. Check Availability​

cURL​

C#​

Response 200 OK​

2. Send a Message​

Request Fields​

Supported Content Types​

Example Request​

cURL​

C#​

Response 200 OK​

3. Get a Message​

cURL​

C#​

Response 200 OK​

4. List Templates​

cURL​

C#​

Response 200 OK​

5. Get a Template​

cURL​

C#​

Response 200 OK​

HTTP Status Codes​

Integration Recommendations​

Purpose

General Information

Base URL

Data Format

Authentication

Correlation

Idempotency

Request Body Validation

Common Setup for C# Examples

1. Check Availability

cURL

C#

Response `200 OK`

2. Send a Message

Request Fields

Supported Content Types

Example Request

cURL

C#

Response `200 OK`

3. Get a Message

cURL

C#

Response `200 OK`

4. List Templates

cURL

C#

Response `200 OK`

5. Get a Template

cURL

C#

Response `200 OK`

HTTP Status Codes

Integration Recommendations