Skip to main content
Conversation endpoints are organized around a lead’s thread. Store the public lead ID and treat message IDs and communication IDs as opaque.

Read a thread

  1. List or locate the lead.
  2. Request GET /api/v1/public/conversations?lead_id=LEAD_ID.
  3. Follow the endpoint’s pagination fields without constructing cursors.
  4. Use message direction and channel to distinguish outbound activity from replies.

Send a message

POST /messages is a real external side effect. Validate the channel, recipient, message type, and content before sending. Do not place this call behind automatic retry middleware unless the endpoint’s idempotency contract is present and reused. Unsupported channel or message combinations return a client error. Delivery acceptance is not the same as recipient delivery; use the returned status and later conversation activity to confirm the outcome.

Traffic-light state

The traffic light is a field on the lead. Set it with PATCH /leads/{lead_id} and {"traffic_light": "green"}. The update returns the lead. Use the allowed values green, yellow, red and unknown. Setting it together with other lead fields is safe: steps run in order and a failure lists the steps already applied under applied.