Add a note to a conversation

Read with ChatGPTRead with Claude

Add an internal note to a conversation. Notes are only visible to your team in the live chat: they are never sent to the contact.

The note is written by the user who owns the API key, and the live chat labels it as sent via API. It doesn't mark the conversation as read for anybody.

Mentions

Mention users of your account to let them know about the note: they get a notification and find the conversation under the Mentions filter of the live chat.

1. List their UUIDs in mentions. Get them from List Account Users. You can only mention active users of your account who can open the conversation: admins, users the conversation's number is shared with, and users the conversation is assigned to, directly or through one of their teams.
2. Write each UUID in text where the mention should go. The live chat shows the user's name there.

A mentioned UUID that doesn't appear in text is added at the beginning of the note.

Endpoint

POST https://api.p.2chat.io/open/conversations/<session-key>/notes

• <session-key> is the session_key of the conversation, e.g. WA-WAN8fd3442f-e111-4fed-9323-1824fd7546c9-14085550176. See where to get it.

Authentication

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

Body

Field	Type	Required	Description
text	string	Yes	The note. Up to 2000 characters. Plain text: HTML is shown as typed.
mentions	array of strings	No	UUIDs of the users to mention, up to 20. They must be able to open the conversation. See mentions.

Invocation

cURL

curl --location --request POST 'https://api.p.2chat.io/open/conversations/WA-WAN8fd3442f-e111-4fed-9323-1824fd7546c9-14085550176/notes' \
--header 'X-User-API-Key: your_api_key_here' \
--header 'Content-Type: application/json' \
--data-raw '{
    "text": "The customer asked for an invoice. USR4f1c8a73-2e91-4d6b-9c44-1a72bfe0d521 can you send it?",
    "mentions": [
        "USR4f1c8a73-2e91-4d6b-9c44-1a72bfe0d521"
    ]
}'

Python

import requests

url = "https://api.p.2chat.io/open/conversations/WA-WAN8fd3442f-e111-4fed-9323-1824fd7546c9-14085550176/notes"
headers = {
    "X-User-API-Key": "your_api_key_here"
}
payload = {
    "text": "The customer asked for an invoice. USR4f1c8a73-2e91-4d6b-9c44-1a72bfe0d521 can you send it?",
    "mentions": [
        "USR4f1c8a73-2e91-4d6b-9c44-1a72bfe0d521"
    ]
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

JavaScript

const axios = require('axios');

const response = await axios.post('https://api.p.2chat.io/open/conversations/WA-WAN8fd3442f-e111-4fed-9323-1824fd7546c9-14085550176/notes', {
        "text": "The customer asked for an invoice. USR4f1c8a73-2e91-4d6b-9c44-1a72bfe0d521 can you send it?",
        "mentions": [
            "USR4f1c8a73-2e91-4d6b-9c44-1a72bfe0d521"
        ]
    }, {
    headers: {
        'X-User-API-Key': 'your_api_key_here'
    }
});

console.log(response.data);

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.p.2chat.io/open/conversations/WA-WAN8fd3442f-e111-4fed-9323-1824fd7546c9-14085550176/notes',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{"text": "The customer asked for an invoice. USR4f1c8a73-2e91-4d6b-9c44-1a72bfe0d521 can you send it?", "mentions": ["USR4f1c8a73-2e91-4d6b-9c44-1a72bfe0d521"]}',
  CURLOPT_HTTPHEADER => array(
    'X-User-API-Key: your_api_key_here',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response

Success (HTTP 201 Created)

{
    "success": true,
    "data": {
        "uuid": "MSG1e9a6c34-77b2-4c0f-9a5e-3f2d8b6e1c90",
        "session_key": "WA-WAN8fd3442f-e111-4fed-9323-1824fd7546c9-14085550176",
        "text": "The customer asked for an invoice. USR4f1c8a73-2e91-4d6b-9c44-1a72bfe0d521 can you send it?",
        "author": {
            "uuid": "USRb2d7e6c0-5f3a-4811-87ce-c9d208a1f4e2",
            "name": "Grace Hopper"
        },
        "mentions": [
            {
                "uuid": "USR4f1c8a73-2e91-4d6b-9c44-1a72bfe0d521",
                "name": "Ada Lovelace"
            }
        ],
        "created_at": "2026-11-09T18:42:10Z"
    }
}

Field	Description
data.uuid	UUID of the note
data.session_key	The conversation the note was added to
data.text	The note as stored, with the mentioned UUIDs that weren't in text added at the beginning
data.author	The user who owns the API key (uuid, name)
data.mentions	The mentioned users (uuid, name)
data.created_at	When the note was created, in UTC

Error

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

HTTP status	When
400	text is empty or longer than 2000 characters, there are more than 20 mentions, or a mentioned UUID isn't an active user of your account or can't open the conversation. The message lists those UUIDs
401	The API key is missing or invalid
403	The user who owns the API key can't open this conversation. See permissions
404	There is no conversation with that session_key in your account
422	text is missing from the body