Before you start
You need an API key with thecustomers:write, conversations:write and conversations:read scopes. See Authentication.
Set it as an environment variable so it never ends up in your code:
1
Create the customer
Send the customer once, with your own id for them as The response includes the customer’s Cerium
externalId.id (starts with prt_). Keep it: you need it to start a conversation.2
Start a conversation
Send the customer’s first message. The The response is the first message. Its
idempotencyKey makes a retry safe: see Idempotency.conversationId identifies the conversation.3
Read the replies
List the conversation’s messages to pick up replies from your team or your AI agent.Each message says who wrote it in
senderType: customer, agent, ai or system.4
Keep the conversation going
Add the customer’s next message:
Next steps
Handle errors
What each status means and what to do about it.
Retry safely
Make sure a retry never sends a message twice.
Going live
A checklist before you ship.