API REFERENCE

Conversations API

The SimplyRCS conversations API has 10 public endpoints. Every endpoint below is documented with its parameters, responses and an example request. The reference is public and needs no account; a scoped API key is required only to make live calls.

Conversation, messaging, inbox, and session APIs.

Base URL https://api.simplyrcs.com · All 195 endpoints · Pricing

GET/v1/conversations

List conversations

GET https://api.simplyrcs.com/v1/conversations · requires an API key

Query parameters

Name	Type	Required
`page`	`integer`	No
`limit`	`integer`	No
`status`	`"BOT" \| "HUMAN" \| "CLOSED"`	No
`channelId`	`string`	No

Responses

Status	Returns	Description
`200`	`ConversationListResponse`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X GET https://api.simplyrcs.com/v1/conversations \
  -H 'Authorization: Bearer YOUR_API_KEY'

GET/v1/conversations/{id}

Get a conversation

GET https://api.simplyrcs.com/v1/conversations/{id} · requires an API key

Path parameters

Name	Type	Description
`id` required	`string`

Responses

Status	Returns	Description
`200`	`ConversationDetail`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X GET https://api.simplyrcs.com/v1/conversations/{id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

GET/v1/conversations/{id}/messages

List conversation messages

Cursor-paginated, newest first. Pass `before` (a message id) to load older pages.

GET https://api.simplyrcs.com/v1/conversations/{id}/messages · requires an API key

Path parameters

Name	Type	Description
`id` required	`string`

Query parameters

Name	Type	Required	Description
`limit`	`integer`	No
`before`	`string`	No	Message id to paginate backwards from.

Responses

Status	Returns	Description
`200`	`ConversationMessagesResponse`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X GET https://api.simplyrcs.com/v1/conversations/{id}/messages \
  -H 'Authorization: Bearer YOUR_API_KEY'

POST/v1/conversations/{id}/messages

Send a conversation message

Sends a message into an existing conversation using its contact, channel, and sender ID.

POST https://api.simplyrcs.com/v1/conversations/{id}/messages · requires an API key

Path parameters

Name	Type	Description
`id` required	`string`

Request body

ConversationSendMessageRequest · optional

Responses

Status	Returns	Description
`200`	`ConversationSendMessageResponse`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X POST https://api.simplyrcs.com/v1/conversations/{id}/messages \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Example request" }'

GET/v1/conversations/{id}/session

Get conversation session details

GET https://api.simplyrcs.com/v1/conversations/{id}/session · requires an API key

Path parameters

Name	Type	Description
`id` required	`string`

Responses

Status	Returns	Description
`200`	`object`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X GET https://api.simplyrcs.com/v1/conversations/{id}/session \
  -H 'Authorization: Bearer YOUR_API_KEY'

GET/v1/conversations/{id}/source

Get conversation source

GET https://api.simplyrcs.com/v1/conversations/{id}/source · requires an API key

Path parameters

Name	Type	Description
`id` required	`string`

Responses

Status	Returns	Description
`200`	`object`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X GET https://api.simplyrcs.com/v1/conversations/{id}/source \
  -H 'Authorization: Bearer YOUR_API_KEY'

POST/v1/conversations/{id}/handoff

Handoff a conversation

Moves a BOT conversation to HUMAN and (by default) auto-assigns the next available agent.

POST https://api.simplyrcs.com/v1/conversations/{id}/handoff · requires an API key

Path parameters

Name	Type	Description
`id` required	`string`

Request body

ConversationHandoffRequest · optional

Responses

Status	Returns	Description
`200`	`ConversationHandoffResponse`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X POST https://api.simplyrcs.com/v1/conversations/{id}/handoff \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Example request" }'

POST/v1/messages/send

Send a direct message

Sends an outbound message to a contact. Pass an optional `Idempotency-Key` header (printable ASCII, max 255 chars) to make retries replay the original response for 24h instead of double-sending. When `messageType` is omitted it defaults to MARKETING, which applies the strictest consent gates.

POST https://api.simplyrcs.com/v1/messages/send · requires an API key

Request body

SendMessageRequest · optional

Responses

Status	Returns	Description
`200`	`SendMessageResponse`	Message accepted and dispatched
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed
`409`	`ErrorResponse`	Idempotency-Key conflict (in progress or reused with a different body)

Example request

curl -X POST https://api.simplyrcs.com/v1/messages/send \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Example request" }'

POST/v1/messages/preview

Preview a rendered message

POST https://api.simplyrcs.com/v1/messages/preview · requires an API key

Request body

PreviewMessageRequest · optional

Responses

Status	Returns	Description
`200`	`PreviewMessageResponse`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X POST https://api.simplyrcs.com/v1/messages/preview \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Example request" }'

POST/v1/messages/{id}/revoke

Revoke a sent message

POST https://api.simplyrcs.com/v1/messages/{id}/revoke · requires an API key

Path parameters

Name	Type	Description
`id` required	`string`

Responses

Status	Returns	Description
`200`	`RevokeMessageResponse`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X POST https://api.simplyrcs.com/v1/messages/{id}/revoke \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Example request" }'

Other parts of the API

Get a free sender ID test Read the RCS API guide