Conversations

Open a conversation and send the first message

Sandbox keys simulate delivery — nothing reaches a phone — so this is safe to call with fake E.164 numbers while you build.

To get two-way messaging without keeping a process alive, attach a flow. Cadence then answers every reply on its own inbound webhook, so a recipient who replies an hour later, after your deploy, still gets the next step. Without one, nothing is answered for you: you drive the conversation yourself over GET /v1/events.

optin is required and records the consent provenance you are asserting.

Three fields worth knowing about, all optional and none obvious: idempotencyKey makes a retry safe — without it a cron that retries double-sends and double-bills, which is the single most expensive omission on this route. turnCeiling caps how long a conversation may run (default 30). phiSafe enforces PHI-safe-minimal content for clinical use.

post/v1/conversations

Request

  • Base URL: https://api.cadencercs.com
  • URL: https://api.cadencercs.com/v1/conversations
  • Auth: HTTP bearer

Request body

agentIdstring required
brandIdstring required
tostring required
useCase'transactional' | 'promo' | 'conversational' | 'leadgen' required
rcsOnlyboolean

Disable SMS delivery for the entire conversation. Requires a backend that guarantees RCS-only sends. Defaults to false.

phiSafeboolean
turnCeilinginteger
idempotencyKeystring

Response

Opened, and the first message sent.

conversationIdstring required
providerMsgIdstring

Opening provider message ID; absent when a flow-only opening is queued.

channel'rcs' | 'sms' | 'queued' required
channelConfidence'provisional' | 'committed'

provisional means we chose a channel and have no confirmation yet. It becomes committed when the channel is proven: on the first delivery receipt from the handset on RCS, or on an SMS fallback caused by the recipient — no RCS on their device, or your agent not launched on their carrier.

A fallback caused by us — a rejected payload, a bad credential, a timeout — leaves this provisional, because it says nothing about the recipient. Committing there would mark a perfectly reachable handset SMS-only for the rest of the conversation on the strength of our own bug, and report it as a fact about their phone. See fellBack.ourFault on the send response.

trustLevel'verified_rcs' | 'branded_sms' | 'unbranded_sms'
serverDrivenboolean

Present when a flow is attached — Cadence answers replies for you.

cardSentboolean

Whether flow.card was rendered. RCS only.

Changes

No recorded changes to this operation across all 1 revision of this API.