List messages

Retrieve a chronological list of messages exchanged between your Quo number and specified participants, with support for filtering and pagination.

GET /v1/messages

List messages

cURL

curl --request GET \
  --url https://dev-public-api.openphone.dev/v1/messages \
  --header 'Authorization: <api-key>'

200

{
  "data": [
    {
      "id": "AC123abc",
      "to": [
        "[phone]"
      ],
      "from": "[phone]",
      "text": "Hello, world!",
      "phoneNumberId": "PN123abc",
      "conversationId": "CN123abc",
      "direction": "incoming",
      "userId": "US123abc",
      "status": "sent",
      "createdAt": "2022-01-01T00:00:00Z",
      "updatedAt": "2022-01-01T00:00:00Z",
      "media": [
        {
          "url": "https://example.com/image.png",
          "type": "image/png"
        }
      ]
    }
  ],
  "totalItems": 123,
  "nextPageToken": "<string>"
}

Authorizations

Authorization · string · header · required

Query Parameters

phoneNumberId · string · required

The unique identifier of the Quo number used to send or receive the messages. PhoneNumberID can be retrieved via the Get Phone Numbers endpoint.

Pattern: ^PN(.*)$

Example:

"OP123abc"

userId · string

The unique identifier of the user the message was sent from.

Pattern: ^US(.*)$

Example:

"US123abc"

participants · string[] · required

Array of phone numbers involved in the conversation, excluding your Quo number, in E.164 format. Passing a single participant will retrieve their conversation messages. Passing multiple participants will retrieve group conversation messages. Repeat the "participants" key for each phone number without brackets, e.g. "participants=%2B15555555555&participants=%2B15555555556".

Maximum array length: 10

A phone number in E.164 format, including the country code.

Pattern: ^\+[1-9]\d{1,14}$

Example:

"[phone]"

since · string<date-time> · deprecated

DEPRECATED, use "createdAfter" or "createdBefore" instead. "since" currently behaves as "createdBefore" and will be removed in an upcoming release.

Example:

"2022-01-01T00:00:00Z"

createdAfter · string<date-time>

Filter results to only include messages created after the specified date and time, in ISO 8601 format.

Example:

"2022-01-01T00:00:00Z"

createdBefore · string<date-time>

Filter results to only include messages created before the specified date and time, in ISO 8601 format.

Example:

"2022-01-01T00:00:00Z"

maxResults · integer · default: 10 · required

Maximum number of results to return per page.

Required range: 1 <= x <= 100

pageToken · string

Response

200

application/json

OK

data · object[] · required

Array of items

Show child attributes

totalItems · integer · required

Total number of items available. ⚠️ Note: totalItems is not accurately returning the total number of items that can be paginated. We are working on fixing this issue.

nextPageToken · string | null · required