Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.1to1ai.com/llms.txt

Use this file to discover all available pages before exploring further.

A conversation is the WhatsApp thread between your business and a contact. Almost every send and action endpoint (/conversation/*) takes it in the request body under the conversation object.

​
Identifying a conversation

The conversation object accepts one of three identifiers. The resolver prioritizes them in this order: uuid → whatsapp_user_id → phone.
​
uuid
string
The UUID from a GET /conversations. The most direct and stable path.
​
whatsapp_user_id
string
The contact’s identifier in Meta. Recommended for new clients — it survives the migration to BSUID.
​
phone
string
Number in E.164 format (+5215512345678). Normalized to digits before the lookup. Useful when all you have is the phone.
{ "conversation": { "phone": "+52 55 1234 5678" } }
// equivalent: { "conversation": { "uuid": "7b8a..." } }
phone and whatsapp_user_id point to the same value today. They coexist for Meta’s transition to alphanumeric identifiers (BSUID). If you’re starting from scratch, store whatsapp_user_id.

​
The 24h window

This is WhatsApp’s core concept and it decides what you can send.
1

The contact messages you

WhatsApp opens a 24-hour window. Each new message from the contact resets the timer.
2

Window open

You can send free-form messages: text, media, and quick replies.
3

24h pass with no reply

The window closes. The only allowed message is a template approved by Meta.
4

Sending a template reopens the window

You can send free-form messages again.
Sending text, media, or a quick reply with the window closed fails with WINDOW_CLOSED (422). Send a template first to reopen it.

​
Checking the window status

Before sending a free-form message, you can verify whether the window is open with POST /conversation/status: 
curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/status" \
  -H "Authorization: Bearer sk_1to1_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "conversation": { "phone": "+5215512345678" } }'
The response includes window.status (open or closed) and window.hours_remaining, plus the assignment, mailbox, tags, and inbox_status of the conversation. Use it to decide between a free-form message and a template.

​
Next steps

Send messages

Text, media, quick replies, and templates.

Templates

How to send templates when the 24h window is closed.