Sending Messages

Learn how to send WhatsApp messages via the API

Sending Messages

TimelinesAI provides multiple ways to send WhatsApp messages depending on your use case.

Sending methods

Method	Best for	Endpoint
By phone number	New contacts, phone from your CRM	POST /messages
By chat ID	Existing conversations	POST /chats/{chat_id}/messages
By chat name	When you know the contact name	POST /messages/to_chat_name
By JID	Groups, technical integrations	POST /messages/to_jid

Send to phone number

The most common method. Works even if you haven’t messaged this number before.

cURL

curl -X POST "https://app.timelines.ai/integrations/api/messages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "[phone]",
    "text": "Hello! Thanks for your interest."
  }'

Phone number format

Use international format with country code:

• ✅ [phone]
• ✅ 14155551234
• ❌ [phone]
• ❌ 415-555-1234

Send to existing chat

When you have a chat_id (from listing chats or webhook events):

cURL

curl -X POST "https://app.timelines.ai/integrations/api/chats/123456/messages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Following up on your question..."
  }'

Choosing a WhatsApp account

If you have multiple WhatsApp numbers connected, specify which one to send from:

{
  "phone": "[phone]",
  "text": "Hello!",
  "whatsapp_account_id": "[e-mail]"
}

If you don’t specify whatsapp_account_id, the most recently connected account is used.

Message formatting

Line breaks

Use \n for line breaks:

{
  "text": "Hello!\n\nHere's your summary:\n- Item 1\n- Item 2"
}

Renders as:

Hello!

Here’s your summary:

• Item 1
• Item 2

Emojis

Emojis are fully supported:

{
  "text": "Thanks for reaching out! 🎉 We'll get back to you soon. 👍"
}

Auto-apply labels

Automatically label chats when sending messages:

{
  "phone": "[phone]",
  "text": "Welcome to our service!",
  "label": "onboarding"
}

This is useful for tracking outreach campaigns or categorizing contacts as you message them.

Tracking delivery

Get message status

After sending, use the message_uid to track delivery:

curl -X GET "https://app.timelines.ai/integrations/api/messages/{message_uid}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Status values

Status	Meaning
queued	Message is waiting to be sent
sent	Message sent to WhatsApp servers
delivered	Message delivered to recipient’s device
read	Recipient opened the message
failed	Message could not be sent

Status history

Get the complete timeline:

curl -X GET "https://app.timelines.ai/integrations/api/messages/{message_uid}/status_history" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "status": "ok",
  "data": [
    { "status": "queued", "timestamp": "2024-01-15T10:30:00Z" },
    { "status": "sent", "timestamp": "2024-01-15T10:30:02Z" },
    { "status": "delivered", "timestamp": "2024-01-15T10:30:05Z" },
    { "status": "read", "timestamp": "2024-01-15T10:32:15Z" }
  ]
}

Rate limits

Messages are sent with a ~2 second delay between each to avoid WhatsApp spam detection.

Sending too many messages too quickly may result in WhatsApp flagging your number. Always respect rate limits.

If you have high-volume needs, contact support to discuss Business plan options.

Credits usage

Message type	Credits
Text only	1
Text + attachment	2
Failed (refunded)	0

Common errors

Invalid phone number

{ "status": "error", "message": "Invalid phone number format" }

Solution: Use international format with country code (e.g., [phone])

WhatsApp account not connected

{ "status": "error", "message": "No connected WhatsApp account" }

Solution: Ensure at least one WhatsApp account is connected in your workspace

Insufficient quota

{ "status": "error", "message": "Message quota exceeded" }

Solution: Upgrade your plan or wait for quota to reset

Next steps

Send attachments

Learn to send images and files

Set up webhooks

Get notified when messages arrive