/v1/conversations

Time	Status	User Agent
Retrieving recent requests…

A "conversation" groups all of the messages between the Apptoto user and a single counterpart -- often a participant on an event. Each conversation has the most recent inbound and outbound message timestamps and links back to the event and participant when applicable.

Field	Type	Required	Description
folder	String	no	Which folder to fetch. Defaults to `inbox`. See below for the full list.
q	String	no	Optional search query using the Apptoto conversation search syntax. See below.
page_size	Number	no	Defaults to 30
page	Number	no	Defaults to 1. `total` is only included when `page=1`.

Folders

Folder	Description
`inbox`	Conversations with at least one inbound message that have not been archived. (Default.)
`inbox-appointments`	Inbox conversations tied to an event.
`inbox-campaigns`	Inbox conversations tied to a campaign event.
`inbox-other`	Inbox conversations with no associated event.
`outbox`	Conversations the user has sent at least one outbound message in.
`outbox-appointments`	Outbox conversations tied to an event.
`outbox-campaigns`	Outbox conversations tied to a campaign event.
`outbox-other`	Outbox conversations with no associated event.
`archived`	Conversations that have been archived.
`spam`	Conversations marked as spam.

Search syntax

The q parameter accepts the same query language used in the Apptoto portal's Inbox/Outbox search. A few examples:

Query	Meaning
`from:[email protected]`	Match conversations from this sender.
`to=+15035551212`	Exact phone match. (`=` is exact, `:` is tokenized.)
`comm_type:sms`	Only SMS conversations.
`event:sent AND delivery_state:delivered`	Sent messages that were delivered.
`auto:true`	Only automated/reminder messages.
`subject:"appointment confirmation"`	Phrase match on the email subject.
`content:reschedule`	Match the message body.

Response

Each conversation has the following fields:

Field	Type	Description
id	Number	The Apptoto id of the conversation.
event	Object or null	The associated event, in the same shape as `/v1/event` (without the participants array).
participant	Object or null	The participant the conversation is with, in the same shape as a participant on `/v1/events`.
conversation_type	String	`sms`, `email`, or `call`.
from	String	Sender phone number or email.
to	String	Recipient phone number or email.
last_out	DateTime or null	When the most recent outbound message was sent.
last_in	DateTime or null	When the most recent inbound message was received.

Example response:

{
  "conversations": [
    {
      "id": 9876,
      "event": {
        "id": 123,
        "calendar_id": 456,
        "start_time": "2026-04-15T12:00:00-07:00",
        "end_time": "2026-04-15T13:00:00-07:00",
        "title": "Demo with Fred",
        "location": "",
        "content": "",
        "is_deleted": false
      },
      "participant": {
        "id": 789,
        "name": "Fred Smith",
        "phone": "650-555-1212",
        "normalized_phone": "+16505551212",
        "email": "[email protected]",
        "state": "confirmed"
      },
      "conversation_type": "sms",
      "from": "+15035550100",
      "to": "+16505551212",
      "last_out": "2026-04-14T17:31:02-07:00",
      "last_in": "2026-04-14T17:33:21-07:00"
    }
  ],
  "total": 1
}

OAuth scope

Calls authenticated with an OAuth 2.0 bearer token must include the messaging:read scope. A token without it receives a 403 insufficient_scope response. HTTP Basic auth is not scope-gated.