This endpoint allows you to list messages in your account.

Listing Messages

A GET returns the messages for your organization, filtering them as needed. Each message has the following attributes:

• id - the ID of the message (int), filterable as id.
• broadcast - the id of the broadcast (int), filterable as broadcast.
• contact - the UUID and name of the contact (object), filterable as contact with UUID.
• urn - the URN of the sender or receiver, depending on direction (string).
• channel - the UUID and name of the channel that handled this message (object).
• direction - the direction of the message (one of incoming or outgoing).
• type - the type of the message (one of text, optin or voice).
• status - the status of the message, one of:
  • queued - incoming that has not yet been handled, or outgoing message that has not yet been sent.
  • handled - incoming that has been handled by a flow or put in the inbox.
  • wired - outgoing that has been wired to a channel.
  • sent - outgoing for which channel has confirmed that it has been sent.
  • delivered - outgoing for which channel has confirmed that it has been delivered to the contact.
  • read - outgoing for which channel has confirmed that it has been read by the contact.
  • errored - outgoing that has errored but will be retried.
  • failed - outgoing that has errored too many times and will no longer be retried.
• visibility - the visibility of the message (one of visible, archived or deleted)
• text - the text of the message received (string). Note this is the logical view and the message may have been received as multiple physical messages.
• attachments - the attachments on the message (array of objects).
• labels - any labels set on this message (array of objects), filterable as label with label name or UUID.
• flow - the UUID and name of the flow if message was part of a flow (object, optional).
• created_on - when this message was either received by the channel or created (datetime) (filterable as before and after).
• sent_on - for outgoing messages, when the channel sent the message (null if not yet sent or an incoming message) (datetime).
• modified_on - when the message was last modified (datetime).

You can also filter by folder where folder is one of inbox, flows, archived, outbox, sent or failed. Note that you cannot filter by more than one of contact, folder, label or broadcast at the same time.

The sort order for the sent folder is the sent date. All other requests are sorted by the message creation date.

Without any parameters this endpoint will return all incoming and outgoing messages ordered by creation date.

Example:

GET /api/v2/messages.json?folder=inbox

Response is the list of messages for that contact, most recently created first:

{
    "next": "http://example.com/api/v2/messages.json?folder=inbox&cursor=cD0yMDE1LTExLTExKzExJTNBM40NjQlMkIwMCUzRv",
    "previous": null,
    "results": [
    {
        "id": 4105426,
        "broadcast": 2690007,
        "contact": {"uuid": "d33e9ad5-5c35-414c-abd4-e7451c69ff1d", "name": "Bob McFlow"},
        "urn": "tel:+1234567890",
        "channel": {"uuid": "9a8b001e-a913-486c-80f4-1356e23f582e", "name": "Vonage"},
        "direction": "out",
        "type": "text",
        "status": "wired",
        "visibility": "visible",
        "text": "How are you?",
        "attachments": [{"content_type": "audio/wav" "url": "http://domain.com/recording.wav"}],
        "labels": [{"name": "Important", "uuid": "5a4eb79e-1b1f-4ae3-8700-09384cca385f"}],
        "flow": {"uuid": "254fd2ff-4990-4621-9536-0a448d313692", "name": "Registration"},
        "created_on": "2016-01-06T15:33:00.813162Z",
        "sent_on": "2016-01-06T15:35:03.675716Z",
        "modified_on": "2016-01-06T15:35:03.675716Z"
    },
    ...
}

Sending a Message

A POST can be used to create and send a new message. Attachments are media object UUIDs returned from POSTing to the media endpoint.

• contact - the UUID of the contact (string)
• text - the text of the message (string)
• attachments - the attachments of the message (list of strings, maximum 10)

Example:

POST /api/v2/messages.json
{
    "contact": "d33e9ad5-5c35-414c-abd4-e7451c69ff1d",
    "text": "Hi Bob",
    "attachments": []
}

You will receive the new message object as a response if successful:

{
    "id": 4105426,
    "broadcast": null,
    "contact": {"uuid": "d33e9ad5-5c35-414c-abd4-e7451c69ff1d", "name": "Bob McFlow"},
    "urn": "tel:+1234567890",
    "channel": {"uuid": "9a8b001e-a913-486c-80f4-1356e23f582e", "name": "Vonage"},
    "direction": "out",
    "type": "text",
    "status": "queued",
    "visibility": "visible",
    "text": "Hi Bob",
    "attachments": [],
    "labels": [],
    "flow": null,
    "created_on": "2023-01-06T15:33:00.813162Z",
    "sent_on": "2023-01-06T15:35:03.675716Z",
    "modified_on": "2023-01-06T15:35:03.675716Z"
}