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}.
  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 /conversations/{lead_id}/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

PATCH /conversations/{lead_id}/traffic-light updates workspace state and returns no content on success. Use the allowed values from the request schema and treat a 204 as successful even though it has no JSON body.