---
title: "Query messages"
method: GET
path: "/v1/projects/{project_id}/messages"
tags: ["Message"]
---

# Query messages

`GET /v1/projects/{project_id}/messages`

## Request

- Base URL: `https://api.telerivet.com`
- URL: `https://api.telerivet.com/v1/projects/{project_id}/messages`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://telerivet.com/oauth/authorize`, token URL `https://api.telerivet.com/oauth/token`)

Queries messages within the given project.

 Note: To be notified of new incoming messages as they are received, use the [Webhook API](https://telerivet.com/api/webhook).

## Path parameters

- `project_id` string, required

## Query parameters

- `label_id` string: ID of Label
- `direction` 'incoming' | 'outgoing'
- `message_type` 'sms' | 'mms' | 'ussd' | 'ussd_session' | 'call' | 'chat' | 'service'
- `source` 'phone' | 'provider' | 'web' | 'api' | 'service' | 'webhook' | 'scheduled' | 'integration' | 'mcp' | 'welcome'
- `starred` boolean
- `status` 'ignored' | 'processing' | 'received' | 'sent' | 'queued' | 'failed' | 'failed_queued' | 'cancelled' | 'delivered' | 'not_delivered' | 'read'
- `time_created[min]` integer: Unix timestamp in seconds
- `time_created[max]` integer: Unix timestamp in seconds
- `external_id` string
- `contact_id` string: ID of Contact
- `phone_id` string: ID of Phone
- `broadcast_id` string: ID of Broadcast
- `scheduled_id` string: ID of ScheduledMessage
- `group_id` string: ID of Group
- `sort` 'default'
- `sort_dir` 'asc' | 'desc'
- `page_size` integer
- `offset` integer
- `marker` string
- `count` boolean

## Response `200`

Successful response. When count=1 parameter is provided, returns {"count": N} instead.

- object
  - `data` Message[]: Array of results (omitted when count=1)
    - `id` string: ID of the message
    - `direction` 'incoming' | 'outgoing': Direction of the message: incoming messages are sent from one of your contacts to your phone; outgoing messages are sent from your phone to one of your contacts
    - `status` 'ignored' | 'processing' | 'received' | 'sent' | 'queued' | 'failed' | 'failed_queued' | 'cancelled' | 'delivered' | 'not_delivered' | 'read': Current status of the message
    - `message_type` 'sms' | 'mms' | 'ussd' | 'ussd_session' | 'call' | 'chat' | 'service': Type of the message
    - `source` 'phone' | 'provider' | 'web' | 'api' | 'service' | 'webhook' | 'scheduled' | 'integration' | 'mcp' | 'welcome': How the message originated within Telerivet
    - `time_created` integer: The time that the message was created on Telerivet's servers
    - `time_sent` integer, nullable: The time that the message was reported to have been sent (null for incoming messages and messages that have not yet been sent)
    - `time_updated` integer: The time that the message was last updated in Telerivet.
    - `from_number` string: The phone number that the message originated from (your number for outgoing messages, the contact's number for incoming messages)
    - `to_number` string: The phone number that the message was sent to (your number for incoming messages, the contact's number for outgoing messages)
    - `content` string: The text content of the message (null for USSD messages and calls)
    - `starred` boolean: Whether this message is starred in Telerivet
    - `simulated` boolean: Whether this message was simulated within Telerivet for testing (and not actually sent to or received by a real phone)
    - `label_ids` string: List of IDs of labels applied to this message
    - `route_params` object, nullable: Route-specific parameters for the message. When sending messages via chat apps such as WhatsApp, the route_params parameter can be used to send messages with app-specific features such as quick replies and link buttons. For more details, see Route-Specific Parameters.
    - `variant` integer, nullable: For outgoing messages sent with `variants`, the index (starting at 0) of the variant used to send the message. Undefined if the default message body was used.
    - `vars` object: Custom variables stored for this message. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.
    - `priority` integer: Priority of this message. Telerivet will attempt to send messages with higher priority numbers first. Only defined for outgoing messages.
    - `send_attempts` number, nullable: The number of times Telerivet has attempted to send the message. Will be greater than 1 if the message has been resent. Only defined for outgoing messages.
    - `error_message` string: A description of the error encountered while sending a message. (This field is omitted from the API response if there is no error message.)
    - `error_code` string: A route-specific error code encountered while sending a message. The error code values depend on the provider and may be described in the provider's API documentation. Error codes may be strings or numbers, depending on the provider. (This field is omitted from the API response if there is no error code.)
    - `external_id` string: The ID of this message from an external SMS gateway provider (e.g. Twilio or Vonage), if available.
    - `num_parts` number, nullable: The number of SMS parts associated with the message, if applicable and if known.
    - `price` number, nullable: The price of this message, if known.
    - `price_currency` string: The currency of the message price, if applicable.
    - `duration` number, nullable: The duration of the call in seconds, if known, or -1 if the call was not answered.
    - `ring_time` number, nullable: The length of time the call rang in seconds before being answered or hung up, if known.
    - `audio_url` string: For voice calls, the URL of an MP3 file to play when the contact answers the call
    - `tts_lang` 'en-US' | 'en-GB' | 'en-GB-WLS' | 'en-AU' | 'en-IN' | 'da-DK' | 'nl-NL' | 'fr-FR' | 'fr-CA' | 'de-DE' | 'is-IS' | 'it-IT' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ru-RU' | 'es-ES' | 'es-US' | 'sv-SE': For voice calls, the language of the text-to-speech voice
    - `tts_voice` 'female' | 'male': For voice calls, the text-to-speech voice
    - `track_clicks` boolean: If true, URLs in the message content are short URLs that redirect to a destination URL.
    - `short_urls` object[]: For text messages containing short URLs, this is an array of objects with the properties `short_url`, `link_type`, `time_clicked` (the first time that URL was clicked), and `expiration_time`. If `link_type` is "redirect", the object also contains a `destination_url` property. If `link_type` is "media", the object also contains an `media_index` property (the index in the media array). If `link_type` is "service", the object also contains a `service_id` property. This property is undefined for messages that do not contain short URLs.
      - `short_url` string: The short URL
      - `link_type` string: Type of link: redirect, media, or service
      - `time_clicked` integer: First time this URL was clicked
      - `expiration_time` integer: When this short URL expires
      - `destination_url` string: Destination URL (when link_type is redirect)
      - `media_index` integer: Index in media array (when link_type is media)
      - `service_id` string: Service ID (when link_type is service)
    - `network_code` string: A string identifying the network that sent or received the message, if known. For mobile networks, this string contains the 3-digit mobile country code (MCC) followed by the 2- or 3-digit mobile network code (MNC), which results in a 5- or 6-digit number. For lists of mobile network operators and their corresponding MCC/MNC values, see [Mobile country code Wikipedia article](https://en.wikipedia.org/wiki/Mobile_country_code). The network_code property may be non-numeric for messages not sent via mobile networks.
    - `media` object[]: Array of media attachments for the text message. This property is undefined for messages that do not contain media files.
      - `url` string: URL of the media file. Note: For files stored by Telerivet (including uploaded files and incoming media attachments), the URL is temporary and may not be valid for more than 1 day.
      - `type` string: MIME type of the media file, or `route_vcard` for the Contact Card of the sending route in a message that has not been sent yet (in which case the other properties are null)
      - `filename` string: Original filename
      - `size` integer: File size in bytes
      - `file_id` string: ID of the stored file, if applicable
    - `mms_parts` object[]: A list of parts in the MMS message (only for incoming MMS messages received via Telerivet Gateway Android app). Each MMS part in the list is an object with the following properties: - cid: MMS content-id - type: MIME type - filename: original filename - size (int): number of bytes - url: URL where the content for this part is stored (secret but publicly accessible, so you could link/embed it in a web page without having to re-host it yourself) In general, the `media` property of the message is recommended for retrieving information about MMS media files, instead of `mms_parts`. The `mms_parts` property is also only present when retrieving an individual MMS message by ID, not when querying a list of messages.
      - `cid` string: MMS content-id
      - `type` string: MIME type
      - `filename` string: Original filename
      - `size` integer: Number of bytes
      - `url` string: URL where the content is stored
    - `time_clicked` integer: If the message contains any short URLs, this is the first time that a short URL in the message was clicked. This property is undefined for messages that do not contain short URLs.
    - `service_id` string: ID of the service that handled the message (for voice calls, the service defines the call flow)
    - `phone_id` string: ID of the phone (basic route) that sent or received the message
    - `contact_id` string: ID of the contact that sent or received the message
    - `route_id` string: ID of the custom route that sent the message (if applicable)
    - `broadcast_id` string: ID of the broadcast that this message is part of (if applicable)
    - `scheduled_id` string: ID of the scheduled message that created this message is part of (if applicable)
    - `user_id` string: ID of the Telerivet user who sent the message (if applicable)
    - `project_id` string: ID of the project this contact belongs to
    - `url` string: URL to the message detail page in the Telerivet web app
  - `truncated` boolean: True if there are more results
  - `next_marker` string: Marker for pagination
  - `page_size` integer: Number of results per page
  - `sort_dir` 'asc' | 'desc': Sort direction
  - `count` integer: Total count of matching items (only when count=1 parameter is provided)

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key or Bearer token
- `404`: Resource not found

---

[API](https://skmtc.dev/telerivet/apis/telerivet-api.md) · [All operations](https://skmtc.dev/telerivet/apis/telerivet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/telerivet/apis/telerivet-api/revisions/4e14b1c8d917?raw)