Send a transactional message

Prerequisites

API credentials (client ID and client secret) from the Developer tab in RCS Studio
An agent already created in RCS Studio with at least one message template (state)
The agent must be launched (not in test mode) to message real numbers, or the recipient must be a registered test device

Step 1: Authenticate

Exchange your credentials for an access token.

curl -X POST https://auth.rcsstudio.ai/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET"

const response = await fetch('https://auth.rcsstudio.ai/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: process.env.CLIENT_ID,
    client_secret: process.env.CLIENT_SECRET,
  }),
});
const { access_token } = await response.json();

Save the returned access_token. See Authentication for full details on token refresh and best practices.

Step 2: Find your agentId and templateId

You need two IDs:

agentId — copy from the RCS Studio URL when viewing your agent, or call GET /agents and find it in the response
templateId — this is the state ID of the message template you want to send. Find it in RCS Studio when editing a state, or call GET /agents/:agentId/states

# List your agents to find agentId
curl https://api.rcsstudio.ai/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Cookie: session="

# List states to find templateId
curl https://api.rcsstudio.ai/agents/ag_abc123/states \
  -H "Authorization: Bearer $TOKEN" \
  -H "Cookie: session="

Step 3: Send the message

curl -X POST https://api.rcsstudio.ai/agents/ag_abc123/messages/order-confirmation/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "+15551234567",
    "params": {
      "firstName": "Sarah",
      "orderId": "ORD-12345",
      "status": "shipped"
    }
  }'

await fetch(
  'https://api.rcsstudio.ai/agents/ag_abc123/messages/order-confirmation/send',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      msisdn: '+15551234567',
      params: {
        firstName: 'Sarah',
        orderId: 'ORD-12345',
        status: 'shipped',
      },
    }),
  },
);

Request fields

Field	Type	Required	Description
`msisdn`	string	Yes	Recipient phone number in E.164 format
`params`	object	No	Key-value pairs injected into the template as `{{ params.key }}`
`messageId`	string (UUID)	No	Optional correlation ID — generated automatically if omitted

Response

{
  "messageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "templateId": "order-confirmation",
  "msisdn": "+15551234567"
}

How template parameters work

Your template accesses passed values via the params variable using Liquid syntax:

Hi {{ params.firstName }}, your order #{{ params.orderId }} has been {{ params.status }}.

Only params is available when sending via this endpoint — data, input, and user are populated by the state machine and won't be present here.