Conversations & Messages

Conversations are the per-contact message threads in your SMBcrm account. Every SMS, email, or other channel message to or from a contact belongs to one. Use these endpoints to search and read conversations, and to send or record the messages inside them.

Base URL: https://services.smbcrm.com · Version header: v3 · Scopes: conversations.readonly, conversations.write, conversations/message.readonly, conversations/message.write. See Scopes.

Search conversations

GET/conversations/search

Search conversations in your account by contact, keyword, or status.

scope conversations.readonlyauth Location token or PIT

locationId is required. Narrow the results with contactId (only conversations with that contact) and query (free-text search across message bodies), filter with status (for example unread or starred), and order with sort (asc/desc) and sortBy (for example last_message_date).

curl "https://services.smbcrm.com/conversations/search?locationId=<location_id>&contactId=<contact_id>&status=unread&sort=desc&sortBy=last_message_date" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "conversations": [
    {
      "id": "<conversation_id>",
      "contactId": "<contact_id>",
      "locationId": "<location_id>",
      "lastMessageBody": "See you at 3pm!",
      "lastMessageType": "TYPE_SMS",
      "type": "TYPE_PHONE",
      "unreadCount": 0,
      "fullName": "Jordan Lee",
      "contactName": "Jordan Lee",
      "email": "jordan@example.com",
      "phone": "+15551234567"
    }
  ],
  "total": 1
}

Retrieve a conversation

GET/conversations/{conversationId}

Fetch a single conversation by ID.

scope conversations.readonlyauth Location token or PIT

type is a numeric channel code here, not the string form that search returns.

curl https://services.smbcrm.com/conversations/<conversation_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "id": "<conversation_id>",
  "locationId": "<location_id>",
  "contactId": "<contact_id>",
  "type": 1,
  "unreadCount": 0,
  "inbox": true,
  "deleted": false,
  "starred": false
}

Create, update & delete a conversation

POST/conversations/

Create a conversation for a contact.

scope conversations.writeauth Location token or PIT

locationId and contactId are both required. Use this to start an empty conversation thread with a contact before you have a message to send.

curl -X POST https://services.smbcrm.com/conversations/ \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "<location_id>",
    "contactId": "<contact_id>"
  }'

201 Created

{
  "success": true,
  "conversation": {
    "id": "<conversation_id>",
    "locationId": "<location_id>",
    "contactId": "<contact_id>",
    "dateAdded": "2026-07-08T15:04:00.000Z",
    "deleted": false
  }
}

PUT/conversations/{conversationId}

Update a conversation, for example to mark it read/unread or starred.

scope conversations.writeauth Location token or PIT

locationId is required in the body even though it’s already in the path.

curl -X PUT https://services.smbcrm.com/conversations/<conversation_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "<location_id>",
    "starred": true,
    "unreadCount": 0
  }'

200 OK

{
  "success": true,
  "conversation": {
    "id": "<conversation_id>",
    "locationId": "<location_id>",
    "contactId": "<contact_id>",
    "unreadCount": 0,
    "starred": true,
    "deleted": false
  }
}

DELETE/conversations/{conversationId}

Permanently delete a conversation and its messages.

scope conversations.writeauth Location token or PIT

curl -X DELETE https://services.smbcrm.com/conversations/<conversation_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{ "success": true }

Messages

Each message object includes both a numeric type and a readable messageType (for example TYPE_SMS). Use messageType unless you need the raw code.

GET/conversations/{conversationId}/messages

List the messages in a conversation.

scope conversations/message.readonlyauth Location token or PIT

curl https://services.smbcrm.com/conversations/<conversation_id>/messages \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "lastMessageId": "<message_id>",
  "nextPage": false,
  "messages": [
    {
      "id": "<message_id>",
      "type": 1,
      "messageType": "TYPE_SMS",
      "locationId": "<location_id>",
      "contactId": "<contact_id>",
      "conversationId": "<conversation_id>",
      "dateAdded": "2026-07-08T15:04:00.000Z",
      "body": "See you at 3pm!",
      "direction": "outbound",
      "status": "delivered",
      "contentType": "text/plain"
    }
  ]
}

GET/conversations/messages/{id}

Fetch a single message by ID.

scope conversations/message.readonlyauth Location token or PIT

curl https://services.smbcrm.com/conversations/messages/<message_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "id": "<message_id>",
  "type": 1,
  "messageType": "TYPE_SMS",
  "locationId": "<location_id>",
  "contactId": "<contact_id>",
  "conversationId": "<conversation_id>",
  "dateAdded": "2026-07-08T15:04:00.000Z",
  "body": "See you at 3pm!",
  "direction": "outbound",
  "status": "delivered",
  "contentType": "text/plain"
}

Send a message

Caution

Send messages from your server, not the browser. A token that can send SMS or email can send them as your account. Never ship it to client-side code. See Token Safety.

POST/conversations/messages

Send an SMS or email message to a contact.

scope conversations/message.writeauth Location token or PIT

contactId is required. Set type to SMS or Email. The rest of the body depends on which you choose.

SMS

curl -X POST https://services.smbcrm.com/conversations/messages \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SMS",
    "contactId": "<contact_id>",
    "message": "Hey Jordan, just confirming our call at 3pm today."
  }'

Email

curl -X POST https://services.smbcrm.com/conversations/messages \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Email",
    "contactId": "<contact_id>",
    "subject": "Confirming our call today",
    "html": "<p>Hey Jordan, just confirming our call at 3pm today.</p>"
  }'

201 Created

{
  "conversationId": "<conversation_id>",
  "messageId": "<message_id>",
  "status": "pending"
}

Note

Sending type: "Email" may require a verified from-address configured in your account first. Set one up before sending, or the message may fail to deliver.

Record an inbound message

If a contact messages you on a channel your account doesn’t handle natively — a custom chat widget, a third-party number — use this endpoint to log what they sent so it appears in their conversation history like any other message.

POST/conversations/messages/inbound

Record an inbound message from an external channel.

scope conversations/message.writeauth Location token or PIT

The body is similar to sending a message, but since there’s no live channel to infer the thread from, conversationId and conversationProviderId are also required. Set type to SMS or Email and supply the matching fields.

curl -X POST https://services.smbcrm.com/conversations/messages/inbound \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SMS",
    "contactId": "<contact_id>",
    "conversationId": "<conversation_id>",
    "conversationProviderId": "<conversation_provider_id>",
    "message": "Sounds good, see you then!"
  }'

201 Created

{
  "success": true,
  "conversationId": "<conversation_id>",
  "messageId": "<message_id>",
  "message": "success"
}

Related

• Contacts: the contactId every conversation and message belongs to.
• Webhooks: receive new messages in real time instead of polling for them.
• Scopes: the exact permissions each endpoint above requires.