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 194 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 $SIMPLYRCS_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 $SIMPLYRCS_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 $SIMPLYRCS_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 $SIMPLYRCS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Example request" }'

The body in this sample is the spec’s placeholder, not a real payload: send the request body type named above with the fields for this operation.

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 $SIMPLYRCS_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 $SIMPLYRCS_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 $SIMPLYRCS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Example request" }'

The body in this sample is the spec’s placeholder, not a real payload: send the request body type named above with the fields for this operation.

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 replay completed responses for 24h. Uncertain provider acceptance returns 502 and retains the key; retries receive 409 during that window. Reconcile before resending; do not use a new key or wait for expiry to bypass uncertainty. 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)
`502`	`ErrorResponse`	Provider acceptance is uncertain, or accepted-send persistence failed. Do not resend automatically; retain the same Idempotency-Key and reconcile the original attempt.

Example request

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

The body in this sample is the spec’s placeholder, not a real payload: send the request body type named above with the fields for this operation.

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 $SIMPLYRCS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Example request" }'

The body in this sample is the spec’s placeholder, not a real payload: send the request body type named above with the fields for this operation.

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 $SIMPLYRCS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Example request" }'

The body in this sample is the spec’s placeholder, not a real payload: send the request body type named above with the fields for this operation.

Other parts of the API

Try RCS on your phone Read the RCS API guide