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 -X POST "https://app.timelines.ai/integrations/api/messages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+14155551234",
    "text": "Hello! Thanks for your interest."
  }'

const response = await fetch('https://app.timelines.ai/integrations/api/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone: '+14155551234',
    text: 'Hello! Thanks for your interest.'
  })
});

import requests

response = requests.post(
    'https://app.timelines.ai/integrations/api/messages',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'phone': '+14155551234',
        'text': 'Hello! Thanks for your interest.'
    }
)

Phone number format

Use international format with country code:

✅ +14155551234
✅ 14155551234
❌ (415) 555-1234
❌ 415-555-1234

Send to existing chat

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

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..."
  }'

const chatId = 123456;
const response = await fetch(
  `https://app.timelines.ai/integrations/api/chats/${chatId}/messages`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      text: 'Following up on your question...'
    })
  }
);

Choosing a WhatsApp account

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

{
  "phone": "+14155551234",
  "text": "Hello!",
  "whatsapp_account_id": "15551234567@s.whatsapp.net"
}

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": "+14155551234",
  "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., +14155551234)

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

Getting Started

Use Cases

Sending Messages

Sending Messages

Sending methods

Send to phone number

Phone number format

Send to existing chat

Choosing a WhatsApp account

Message formatting

Line breaks

Emojis

Auto-apply labels

Tracking delivery

Get message status

Status values

Status history

Rate limits

Credits usage

Common errors

Next steps

Send attachments

Set up webhooks

​Sending Messages

​Sending methods

​Send to phone number

​Phone number format

​Send to existing chat

​Choosing a WhatsApp account

​Message formatting

​Line breaks

​Emojis

​Auto-apply labels

​Tracking delivery

​Get message status

​Status values

​Status history

​Rate limits

​Credits usage

​Common errors

​Next steps

Send attachments

Set up webhooks

Sending Messages

Sending methods

Send to phone number

Phone number format

Send to existing chat

Choosing a WhatsApp account

Message formatting

Line breaks

Emojis

Auto-apply labels

Tracking delivery

Get message status

Status values

Status history

Rate limits

Credits usage

Common errors

Next steps