Get SMS Messages

Agent Skill

Automate this endpoint with an AI agent using the 2chat-sms skill:

npx skills add 2ChatCo/agent-skills -s 2chat-sms

Get the SMS thread between one of your SMS channels and a contact phone number. Inbound and outbound messages are merged into a single list, ordered oldest to newest.

Endpoint

GET https://api.p.2chat.io/open/sms/messages/{channel_uuid}/{contact_number}

Authentication

Include your API key in the X-User-API-Key header. Learn more about authentication.

Path parameters

Parameter	Description	Example
`channel_uuid`	The UUID of the SMS channel (prefixed `SMS`)	`SMS9a3f1c20-4e7b-4d8a-9c61-2f5b8d0a4e13`
`contact_number`	The contact's phone number in E.164 format	`+447700900123`

Query parameters

Parameter	Description	Example
`results_per_page`	Number of messages to return, between `1` and `200`. Default is `50`	`50`
`before_ts`	Unix timestamp (seconds). Returns only messages older than this value — use it as a cursor to page back in time	`1718790043`

Paging back in time

The thread is returned oldest to newest. To load older messages, take the timestamp of the earliest message you already have and pass it as before_ts on the next request.

Invocation

cURL
Python
JavaScript
PHP

curl -L -G 'https://api.p.2chat.io/open/sms/messages/SMS9a3f1c20-4e7b-4d8a-9c61-2f5b8d0a4e13/+447700900123?results_per_page=50' \
    --header 'X-User-API-Key: your_api_key_here'

import requests

url = "https://api.p.2chat.io/open/sms/messages/SMS9a3f1c20-4e7b-4d8a-9c61-2f5b8d0a4e13/+447700900123"
headers = {
    "X-User-API-Key": "your_api_key_here"
}
params = {
    "results_per_page": 50
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const axios = require('axios');

const response = await axios.get(
    'https://api.p.2chat.io/open/sms/messages/SMS9a3f1c20-4e7b-4d8a-9c61-2f5b8d0a4e13/+447700900123',
    {
        params: { results_per_page: 50 },
        headers: {
            'X-User-API-Key': 'your_api_key_here'
        }
    }
);

console.log(response.data);

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.p.2chat.io/open/sms/messages/SMS9a3f1c20-4e7b-4d8a-9c61-2f5b8d0a4e13/+447700900123?results_per_page=50',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'X-User-API-Key: your_api_key_here'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response

Each message is tagged with a direction (inbound or outbound) and a unix timestamp. Inbound and outbound messages carry slightly different fields.

Success (HTTP 200 OK)

{
    "success": true,
    "count": 2,
    "messages": [
        {
            "uuid": "SMI4f2a1c33-7b6e-4d9a-8c12-9f0e1a2b3c4d",
            "destination": "+13057654321",
            "source": "+447700900123",
            "text": "Hi, is my order ready?",
            "direction": "inbound",
            "price": 0.0,
            "voip_number_setup_id": 42,
            "created_at": "2026-06-20T10:58:02Z",
            "updated_at": "2026-06-20T10:58:02Z",
            "timestamp": 1718883482
        },
        {
            "uuid": "SMOe8b1d572-6a4c-4f93-8d20-1c7b5e0a9f64",
            "destination": "+447700900123",
            "source": "+13057654321",
            "text": "Yes! It ships today.",
            "fragments": 1,
            "direction": "outbound",
            "price": 0.0075,
            "voip_number_setup_id": 42,
            "created_at": "2026-06-20T11:01:30Z",
            "updated_at": "2026-06-20T11:01:30Z",
            "timestamp": 1718883690
        }
    ]
}

Field	Description
`success`	`true` when the request was successful
`count`	Number of messages returned in this response
`messages`	Array of message objects, oldest to newest (see below)

Each message object contains:

Field	Description	Example
`uuid`	Unique identifier of the message. Inbound is prefixed `SMI`, outbound `SMO`	`SMI4f2a1c33-7b6e-4d9a-8c12-9f0e1a2b3c4d`
`destination`	Recipient phone number in E.164 format	`+13057654321`
`source`	Sender phone number in E.164 format	`+447700900123`
`text`	The message content	`Hi, is my order ready?`
`direction`	`inbound` (received) or `outbound` (sent)	`inbound`
`fragments`	Number of SMS segments (outbound messages only)	`1`
`price`	The amount billed to you for the message, in USD	`0.0075`
`voip_number_setup_id`	Internal identifier of the underlying virtual number setup	`42`
`created_at`	When the message was created (UTC)	`2026-06-20T10:58:02Z`
`updated_at`	When the message was last updated (UTC)	`2026-06-20T10:58:02Z`
`timestamp`	Unix timestamp (seconds) of the message	`1718883482`

Error

{
    "error": true,
    "error_message": "Description of what went wrong"
}

Field	Description
`error`	`true` when the request failed
`error_message`	A description of what went wrong

A channel that doesn't exist or doesn't belong to your account returns 404 Not Found.

Get SMS Messages

Endpoint​

Authentication​

Path parameters​

Query parameters​

Invocation​

Response​

Success (HTTP 200 OK)​

Error​