List WABA Conversations Programmatically

Agent Skill

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

npx skills add 2ChatCo/agent-skills -s 2chat-whatsapp-waba

This endpoint lists the conversations of one of your WhatsApp Business API numbers — each contact together with the state of its latest activity — most recently active first.

Endpoint

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

Authentication

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

Parameters

Parameter	In	Required	Description
`channel_uuid`	path	Yes	The `WAN…` UUID of your WABA number (e.g. `WAN95841312-b54d-46e3-b0bc-6414f4a5296b`)
`page_number`	query	No	Zero-based page. Defaults to `0`
`results_per_page`	query	No	Conversations per page, between `1` and `200`. Defaults to `10`
`phone_number`	query	No	Narrows the list to contacts whose number contains this value. Between 3 and 20 digits

info

You need the UUID of the channel first. Get it from Get Numbers.

Paging

page_number is zero-based and results_per_page decides how many conversations each one holds, defaulting to 10:

Page 0, the most recently active: https://api.p.2chat.io/open/waba/conversations/WAN95841312-b54d-46e3-b0bc-6414f4a5296b
Page 1, the 10 before those: https://api.p.2chat.io/open/waba/conversations/WAN95841312-b54d-46e3-b0bc-6414f4a5296b?page_number=1
100 at a time: https://api.p.2chat.io/open/waba/conversations/WAN95841312-b54d-46e3-b0bc-6414f4a5296b?results_per_page=100

Searching by number

?phone_number=123456 returns the conversations whose contact number contains 123456. The value you searched for comes back as search_term.

Invocation

cURL
Python
JavaScript
PHP

curl --location --request GET 'https://api.p.2chat.io/open/waba/conversations/WAN95841312-b54d-46e3-b0bc-6414f4a5296b?page_number=0' \
--header 'X-User-API-Key: your_api_key_here'

import requests

url = "https://api.p.2chat.io/open/waba/conversations/WAN95841312-b54d-46e3-b0bc-6414f4a5296b"
headers = {
    "X-User-API-Key": "your_api_key_here"
}

response = requests.get(url, params={"page_number": 0, "results_per_page": 10}, headers=headers)

print(response.json())

const axios = require('axios');

const response = await axios.get('https://api.p.2chat.io/open/waba/conversations/WAN95841312-b54d-46e3-b0bc-6414f4a5296b', {
    params: { page_number: 0, results_per_page: 10 },
    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/waba/conversations/WAN95841312-b54d-46e3-b0bc-6414f4a5296b?page_number=0',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  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,
    "page_number": 0,
    "results_per_page": 10,
    "total": 2,
    "sessions": [
        {
            "session_key": "WA-WAN95841312-b54d-46e3-b0bc-6414f4a5296b-5215512345432",
            "friendly_name": "Ana",
            "region_name": "Mexico City, FD",
            "iso_country_code": "MX",
            "device": null,
            "channel_uuid": "WAN95841312-b54d-46e3-b0bc-6414f4a5296b",
            "phone_number": "+5215512345432",
            "timezone": "America/Mexico_City",
            "profile_pic_url": null,
            "is_group_chat": false,
            "last_user_message_sent_at": "2026-09-20T14:03:11Z",
            "last_activity_at": "2026-09-20T14:05:48Z",
            "created_at": "2026-08-14T09:21:07Z",
            "contact": {
                "id": 4471,
                "uuid": "CONe6226cd2-cb09-491f-9854-8a9b0626406a",
                "first_name": "Ana",
                "last_name": "Duarte",
                "channel_uuid": null,
                "profile_pic_url": null
            }
        },
        {
            "session_key": "WA-WAN95841312-b54d-46e3-b0bc-6414f4a5296b-17131234567",
            "friendly_name": null,
            "region_name": "Houston, TX",
            "iso_country_code": "US",
            "device": null,
            "channel_uuid": "WAN95841312-b54d-46e3-b0bc-6414f4a5296b",
            "phone_number": "+17131234567",
            "timezone": "America/Chicago",
            "profile_pic_url": null,
            "is_group_chat": false,
            "last_user_message_sent_at": null,
            "last_activity_at": "2026-09-18T22:40:19Z",
            "created_at": "2026-09-18T22:39:55Z"
        }
    ]
}

Field	Description
`success`	`true` when the request was successful
`page_number`	The page you asked for, echoed back
`results_per_page`	The page size in effect, echoed back
`total`	How many conversations matched, within the 1000-conversation window described above
`search_term`	Present only when you passed `phone_number`; the value that was searched
`sessions`	The page of conversations, most recently active first
`sessions[].session_key`	The conversation's key. Pass it to Get a Message
`sessions[].friendly_name`	The contact's WhatsApp display name, when known
`sessions[].phone_number`	The contact's phone number
`sessions[].region_name`	Region the number is registered in, when known
`sessions[].iso_country_code`	Country of the number
`sessions[].timezone`	Timezone of the number
`sessions[].channel_uuid`	Your WABA channel the conversation belongs to
`sessions[].profile_pic_url`	The contact's profile picture, when available
`sessions[].is_group_chat`	Always `false` on WABA — the Cloud API has no group messaging
`sessions[].last_user_message_sent_at`	When the contact last wrote to you, UTC
`sessions[].last_activity_at`	When the conversation last had any activity, UTC
`sessions[].created_at`	When the conversation started, UTC
`sessions[].contact`	The matching 2Chat contact, when the number is in your contacts

Error

{
    "error": true,
    "error_message": "WhatsApp Profile setup not found"
}

HTTP	When
`400`	The page starts at or past the end of the 1000-conversation window
`404`	The channel is not a WABA number of your account
`422`	`channel_uuid` is not a `WAN…` UUID, `page_number` is negative, or `results_per_page` is outside 1–200

List WABA Conversations Programmatically

Endpoint​

Authentication​

Parameters​

Paging​

Invocation​

Response​

Success (HTTP 200 OK)​

Error​