Messages

The in-app conversation with the customer. Everything here matches the Messages screen in the app.

Read

GET /v1/leads/{id}/messages        scope messages:read
{"messages":[
  {"id":"msg_902","lead_id":"6b1c...","direction":"out","body":"Hi Pat, I can come Tuesday at 9.","created_at":"2026-10-22T16:07:40Z","read_at":"2026-10-22T16:20:01Z"},
  {"id":"msg_903","lead_id":"6b1c...","direction":"in","body":"Tuesday works","created_at":"2026-10-22T16:20:45Z","read_at":null}
]}
  • direction: in from the customer, out from you.
  • read_at on an out message is when the customer read it. Reading the list through the API marks the customer's messages read, the same as opening the thread in the app.
  • Up to 500 messages, oldest first. The lead must be accepted.

Send

POST /v1/leads/{id}/messages       scope messages:write
Content-Type: application/json
Idempotency-Key: <unique per message>

{"body":"See you Tuesday at 9."}

Returns 201 with the message. The customer is notified the same way as a message from the app.

Rules (same as the app):

  • The lead must be accepted and not declined.
  • The customer must have an account (can_message on the lead). If not, call or email them (409).
  • 1 to 1,000 characters; up to 20 messages a minute.
  • Keep the conversation on the platform. Our Pro Agreement and API Terms apply to every message.

Events

message.received and message.sent webhooks carry the message object, so a CRM inbox can show replies the moment they arrive.