Before you start

You need an API key with the customers: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 externalId.
The response includes the customer’s Cerium id (starts with prt_). Keep it: you need it to start a conversation.
2

Start a conversation

Send the customer’s first message. The idempotencyKey makes a retry safe: see Idempotency.
The response is the first message. Its 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.