List messages | Dial — Communication Stack for AI Agents

{
  "messages": [
    {
      "id": "string",
      "phoneNumberId": "string",
      "from": "+14155550123",
      "to": "+14155559876",
      "groupId": null,
      "body": "string",
      "direction": "inbound",
      "channel": "sms",
      "service": "imessage",
      "status": "delivered",
      "statusError": null,
      "deliveryState": "delivered",
      "readState": "unread",
      "readAt": null,
      "deliveryError": null,
      "media": [
        {
          "id": "a3f9c2d41e8b4f0a9c6d2e7b5a1f8c30",
          "url": "https://getdial.ai/public-media/a3f9c2d41e8b4f0a9c6d2e7b5a1f8c30.jpg",
          "contentType": "image/jpeg",
          "originalUrl": "https://your-cdn.example.com/summary.png"
        }
      ],
      "replyToId": null,
      "reaction": null,
      "poll": null,
      "pollVote": null,
      "createdAt": "2024-01-15T09:30:00Z"
    }
  ]
}

Returns up to 100 of the most recent messages on the account’s numbers.

Searching. search matches the message body, case-insensitively, anywhere in the text — it is a substring match, not a word search, so voice matches “invoiced”. It searches your whole history, not just the 100 messages an unfiltered call returns, and then returns the 100 most recent matches. It combines with every other filter.

A message whose content was cleared by data retention has an empty body and so matches nothing; the same is true of a media-only message, which is matched by neither its attachment’s name nor its content.

Authentication

AuthorizationBearer

Your Dial API key, sent as Authorization: Bearer sk_live_...

Query parameters

searchstringOptional

Case-insensitive substring match on the message body. Whitespace-only values are ignored, as though the parameter were absent.

contactstringOptional

One conversation: messages exchanged with this number, in both directions, across every line on the account. Group messages are never included — a group message is addressed to the group, and matching it against the participant who sent it would file their whole group into a private thread. Use groupId for those.

numberIdstringOptional

Filter to a single phone number. A replaced number's ID filters to the number that replaced it, whose history includes the replaced number's.

groupIdstringOptional

Filter to a single group conversation (see List groups). Combines with the other filters. A group ID that isn’t on your account returns an empty list rather than an error.

directionenumOptional

Allowed values:

sincedatetimeOptional

Only messages created after this timestamp.

Response

Messages, newest first.

messageslist of objectsOptional

Errors

401

Unauthorized Error