List SMS Conversations

Agent Skill

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

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

List the conversations on an SMS channel — one entry per distinct contact, each with its latest message — ordered newest first.

Endpoint

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

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`

Query parameters

Parameter	Description	Example
`page_number`	Zero-based page index to return. Default is `0`	`0`
`results_per_page`	Number of conversations per page, between `1` and `200`. Default is `20`	`20`

Invocation

cURL
Python
JavaScript
PHP

curl -L -G 'https://api.p.2chat.io/open/sms/conversations/SMS9a3f1c20-4e7b-4d8a-9c61-2f5b8d0a4e13?page_number=0&results_per_page=20' \
    --header 'X-User-API-Key: your_api_key_here'

import requests

url = "https://api.p.2chat.io/open/sms/conversations/SMS9a3f1c20-4e7b-4d8a-9c61-2f5b8d0a4e13"
headers = {
    "X-User-API-Key": "your_api_key_here"
}
params = {
    "page_number": 0,
    "results_per_page": 20
}

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/conversations/SMS9a3f1c20-4e7b-4d8a-9c61-2f5b8d0a4e13',
    {
        params: { page_number: 0, results_per_page: 20 },
        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/conversations/SMS9a3f1c20-4e7b-4d8a-9c61-2f5b8d0a4e13?page_number=0&results_per_page=20',
  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

Success (HTTP 200 OK)

{
    "success": true,
    "count": 2,
    "page": 0,
    "conversations": [
        {
            "contact": "+447700900123",
            "last_message_text": "Thanks, see you then!",
            "last_message_direction": "inbound",
            "last_message_ts": 1718884512,
            "last_message_at": "2026-06-20T11:15:12Z",
            "message_count": 8
        },
        {
            "contact": "+13105550147",
            "last_message_text": "Your code is 4821",
            "last_message_direction": "outbound",
            "last_message_ts": 1718790043,
            "last_message_at": "2026-06-19T09:00:43Z",
            "message_count": 3
        }
    ]
}

Field	Description
`success`	`true` when the request was successful
`count`	Total number of distinct contacts (conversations) on the channel, across all pages
`page`	The zero-based page index returned
`conversations`	Array of conversation objects (see below)

Each conversation object contains:

Field	Description	Example
`contact`	The contact's phone number in E.164 format	`+447700900123`
`last_message_text`	The text of the most recent message in the conversation	`Thanks, see you then!`
`last_message_direction`	Direction of the most recent message: `inbound` or `outbound`	`inbound`
`last_message_ts`	Unix timestamp (seconds) of the most recent message	`1718884512`
`last_message_at`	ISO-8601 UTC timestamp of the most recent message	`2026-06-20T11:15:12Z`
`message_count`	Total number of messages exchanged with this contact	`8`

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.

List SMS Conversations

Endpoint​

Authentication​

Path parameters​

Query parameters​

Invocation​

Response​

Success (HTTP 200 OK)​

Error​