Inbound SMS Synchronisation

If you would rather poll for inbound SMS than receive Webhooks, you can use the Inbound SMS Synchronisation endpoint. It gives you a cursor-based feed of inbound messages for your Workspace, ordered oldest first, which you can poll on any schedule that suits you.

How it works

1. Make your first request with no cursor. Optionally pass from to start at a point in time; if you omit it, the feed starts from now and only returns new messages.
2. Process the returned messages and store the nextCursor value.
3. On your next poll, pass the stored value as cursor. You will only receive messages you have not seen yet.
4. If hasMore is true, call again immediately with the new cursor to drain the backlog before returning to your normal polling interval.

Note

Messages are held back for a few seconds before they appear in the feed to guarantee ordering. A message you have just received may not show up until your next poll, so this endpoint is best suited to integrations that can tolerate a small delay. If you need messages instantly, use Webhooks.

REST API Reference

GET

/sms/inbound/sync

Request Data

Headers

X-Api-Key

required

string

The API Key for your Workspace.

Query Parameters

cursor

string

format: max 64 chars

The nextCursor value from your previous response. Treat it as opaque and store it as-is. Cannot be combined with from.

from

string

format: date-time (ISO 8601)

The date (UTC) in ISO 8601 format to start the feed from. Only valid on the first request, without a cursor. Defaults to now.

inboundNumber

string

format: max 20 chars

Filter to messages received on a specific inbound number. The leading + is optional.

limit

integer

Maximum number of messages to return per page, between 1 and 100. Defaults to 100.

Response Data

JSON Data

messages

array

The inbound messages, ordered oldest first. Empty if there is nothing new.

messages[].id

string

format: long / int64

The inbound message ID from Connect.

messages[].from

string

The phone number the message was sent from.

messages[].to

string

The inbound number the message was sent to.

messages[].body

string

The content of the message.

messages[].receivedAt

string

format: date-time (ISO 8601)

The date (UTC) the message was received.

nextCursor

string

Pass this as cursor on your next request. Always returned, even when the page is empty.

hasMore

boolean

Whether more messages are immediately available. If true, call again straight away with the new cursor.

Integration Sample

cURL

First request, then polling with the cursor

# First request: start the feed from now
curl "https://connect-api.divergent.cloud/sms/inbound/sync" \
-H "X-Api-Key: { API_KEY }"

# Subsequent requests: pass the nextCursor from the previous response
curl "https://connect-api.divergent.cloud/sms/inbound/sync?cursor={ CURSOR }" \
-H "X-Api-Key: { API_KEY }"

An example response:

{
  "messages": [
    {
      "id": "482113470154772480",
      "from": "+447700900123",
      "to": "447700900001",
      "body": "Yes please, book me in",
      "receivedAt": "2026-08-18T09:41:07Z"
    }
  ],
  "nextCursor": "djE6NDgyMTEzNDcwMTU0NzcyNDgw",
  "hasMore": false
}