API reference

WeTarseel API

Send WhatsApp messages, media, templates, and CRM leads.

Base URL: https://app.wetarseel.ai/api/v1
Authentication: Authorization: Bearer YOUR_API_KEY

Authentication

Send your API key as a bearer token in the Authorization header of every request.

Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your account's API key. Copy it from API Keys in the WeTarseel app. Keep the key on your server: anyone who has it can message your customers.

Get your API key

Before you send

to is a WhatsApp phone number in international form without “+” (for example 971501234567) or a Meta BSUID (for example LY.2339455133288574). A phone number maps to WhatsApp Graph to; a BSUID maps to Graph recipient.
/add-lead is the exception: its phone_number includes the leading “+”. It writes a CRM contact and does not send a WhatsApp message.
Free-form text, interactive buttons, interactive lists and /send-media need an open 24-hour window: the contact must have messaged your business in the last 24 hours.
Approved template messages (template_name, including /send-message-with-file) can be sent at any time.
/send-media and /send-message-with-file are multipart form uploads. Every other endpoint takes JSON.
Button replies use 1 to 3 buttons, each with a unique id and a title.

Choosing an endpoint

Endpoint	24-hour window	Template	Media	Best for
`POST /send-message`	Required for free-form text. Not required for an approved template.	Optional	None	General chat, order updates
`POST /send-message with interactive`	Required	None	None	Buttons and list menus inside an open conversation
`POST /send-media`	Required	None	Images, videos, PDFs, audio	Customer replies and photos on request
`POST /send-message-with-file`	Not required	Meta template required	Header attachments	Marketing broadcasts and PDF invoices
`POST /add-lead`	Not applicable	None	None	Website forms and lead sync. Does not send a WhatsApp message.

Send Message

POST/api/v1/send-message

Send plain text or approved Meta template messages. Address contacts by phone number or Meta BSUID.

24-hour window

Free-form text vs. templates. Free-form text requires an active 24-hour conversation window. Approved templates can be sent anytime.

Parameters

Content type: application/json

tostringRequired
Recipient WhatsApp phone (country code, no "+", e.g. "971501234567") or Meta Business-Scoped User ID / BSUID (e.g. "LY.2339455133288574", "PK.1643668637275009"). Phone maps to Graph "to"; BSUID maps to Graph "recipient".
messagestringOptional
Plain text body. Required if template_name is not provided (24h window applies).
template_namestringOptional
Meta-approved WhatsApp template name (can be sent anytime).
parametersstring[]Optional
Array of positional strings for template variables: ["John", "INV-102"].

Example request

# Free-form text (phone)
curl -X POST https://app.wetarseel.ai/api/v1/send-message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "971501234567",
    "message": "Hello from WeTarseel!"
  }'

# Free-form text (BSUID)
curl -X POST https://app.wetarseel.ai/api/v1/send-message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "LY.2339455133288574",
    "message": "Hello from WeTarseel!"
  }'

# Template message
curl -X POST https://app.wetarseel.ai/api/v1/send-message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "971501234567",
    "template_name": "welcome_message",
    "parameters": ["John Doe"]
  }'

Example response

200 OK

{
  "success": true,
  "messageId": "msg_98f4a1c0",
  "status": "sent"
}

Interactive Buttons & Lists

POST/api/v1/send-message

Send interactive CTA buttons (1–3 buttons) or list menus during active conversations.

24-hour window

24-hour window required. Interactive buttons and list menus must be sent within 24 hours of the recipient's last inbound message.

Parameters

Content type: application/json

tostringRequired
Recipient WhatsApp phone (e.g. "971501234567") or Meta BSUID (e.g. "LY.2339455133288574"). Same rules as Send Message.
interactive.type"button" | "list"Required
"button" for 1-3 buttons, or "list" for menu lists.
interactive.body_textstringRequired
Main body message content (max 1024 characters).
interactive.headerstringOptional
Optional header text displayed above the body (max 60 chars).
interactive.footerstringOptional
Optional footer text displayed in small font (max 60 chars).
interactive.buttonsArray<{ id, title }>Optional
Array of 1-3 button items with unique IDs and titles.
interactive.sectionsArray<{ title, rows }>Optional
For list type: array of section objects with rows.

Example request

curl -X POST https://app.wetarseel.ai/api/v1/send-message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "971501234567",
    "interactive": {
      "type": "button",
      "body_text": "Would you like to schedule an appointment?",
      "buttons": [
        {"id": "yes_book", "title": "Yes, book now"},
        {"id": "no_thanks", "title": "Not now"}
      ]
    }
  }'

Example response

200 OK

{
  "success": true,
  "messageId": "msg_87d52a1b",
  "status": "sent"
}

Send Media (Free-form)

POST/api/v1/send-media

Send photos, documents, videos, and audio in active conversations without templates.

24-hour window

24-hour window required. Recipient must have messaged within the last 24 hours. For marketing outside 24h, use a template with file.

Parameters

Content type: multipart/form-data

fileFile (Binary)Required
Media file: Images (<5MB), Videos (<16MB), Documents (<100MB), Audio (<16MB).
tostringRequired
Recipient phone number with country code.
captionstringOptional
Optional text caption (max 1024 chars).

Example request

curl -X POST https://app.wetarseel.ai/api/v1/send-media \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "to=971501234567" \
  -F "[email protected]" \
  -F "caption=Here is the photo you requested!"

Example response

200 OK

{
  "success": true,
  "messageId": "msg_98a72c1d",
  "mediaUrl": "https://..."
}

Send Template with File

POST/api/v1/send-message-with-file

Send WhatsApp template messages containing media attachments (PDF invoices, product images, videos).

Any time

No 24-hour window required. Can be sent at any time for proactive marketing, order confirmations, and invoices.

Parameters

Content type: multipart/form-data

fileFile (Binary)Required
Media file matching the template header format (Image, Video, Document).
tostringRequired
Recipient phone number with country code.
template_namestringRequired
Meta-approved template configured with a Media Header.
parametersstring (JSON array)Optional
JSON string array for body variables: '["John Doe", "INV-1234"]'.

Example request

curl -X POST https://app.wetarseel.ai/api/v1/send-message-with-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "to=971501234567" \
  -F "template_name=invoice_template" \
  -F 'parameters=["John Doe","INV-12345"]'

Example response

200 OK

{
  "success": true,
  "messageId": "msg_43f11b98",
  "status": "delivered"
}

Add / Update CRM Lead

POST/api/v1/add-lead

Create or update contacts, assign tags, lists, and custom metadata in WeTarseel CRM.

CRM

CRM lead management. Sync customer records from your website, CRM, or checkout in real time. This doesn't send a WhatsApp message.

Parameters

Content type: application/json

phone_numberstringRequired
Phone number with country code (e.g. "+971521345678").
namestringOptional
Customer full name (defaults to phone number if omitted).
list_namestringOptional
Destination CRM list name (created automatically if not found).
statusstringOptional
Lead status (e.g. "New", "Contacted"). Default: "New".
tagsstring[]Optional
Array of tag strings: ["customer", "vip"].
metaobjectOptional
Custom JSON object for order IDs or campaign tracking.

Example request

curl -X POST https://app.wetarseel.ai/api/v1/add-lead \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+971521345678",
    "name": "John Doe",
    "list_name": "API Customers",
    "status": "New",
    "tags": ["customer", "vip"]
  }'

Example response

200 OK

{
  "success": true,
  "message": "Lead created successfully",
  "data": {
    "leadId": "lead_98a7c6b5",
    "phoneNumber": "971521345678",
    "name": "John Doe",
    "status": "New",
    "tags": [
      "customer",
      "vip"
    ]
  }
}

Webhooks

Outbound webhooks

WeTarseel sends HTTP POST requests to your endpoint when subscribed events occur.

Set up

In the WeTarseel app, open the webhook settings and find Outbound Webhooks.
Enter your Endpoint URL. It must be a valid HTTPS URL reachable over the public internet, for example https://api.yourdomain.com/webhooks/wetarseel.
Under Subscribed Events, tick the events you want (or Select All), then Save Settings.

Payload format

Every event is a JSON body with the same four top-level fields.

eventstring
Which event this is, e.g. "message_received". Route on this field.
timestampstring
When the event happened, in ISO 8601 UTC, e.g. "2026-11-09T10:51:14.827Z".
account_idstring
Your WeTarseel account. Message Status sends it as accountId.
dataobject
The event's details. Its fields depend on the event (samples below).

Example receiver

A minimal endpoint that routes on the event field.

// Express: one endpoint for every subscribed event
import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/wetarseel', (req, res) => {
  const { event, data } = req.body;

  switch (event) {
    case 'message_received':
      console.log(`${data.sender_name} (${data.from}): ${data.text?.body}`);
      break;
    case 'message_status':
      console.log(`${data.messageId} is ${data.status}`);
      break;
    case 'order_received':
      console.log(`Order ${data.order_id}: ${data.total} ${data.currency}`);
      break;
  }

  res.sendStatus(200);
});

app.listen(3000);

Events

Subscribe to any of these in your webhook settings. Each sample is the body WeTarseel posts to your endpoint.

Message Received

Inbound

eventmessage_received

Triggered whenever a user sends an incoming text, media, or button response.

{
  "event": "message_received",
  "timestamp": "2026-11-09T10:51:14.827Z",
  "account_id": "acc_12345",
  "data": {
    "message_id": "wamid.HBgLM...",
    "from": "971501234567",
    "sender_name": "Sarah Connor",
    "type": "text",
    "text": {
      "body": "Hello! I need assistance with my order."
    }
  }
}

Message Sent

Outbound

eventmessage_sent

Triggered when an outbound message is dispatched (WhatsApp Coexist).

{
  "event": "message_sent",
  "timestamp": "2026-11-09T10:51:14.827Z",
  "account_id": "acc_12345",
  "data": {
    "message_id": "msg_98f4a1c0",
    "to": "971501234567",
    "type": "text",
    "text": {
      "body": "We have dispatched your order!"
    }
  }
}

Lead Added

CRM

eventlead_added

Triggered when a new lead is captured or imported into your account.

{
  "event": "lead_added",
  "timestamp": "2026-11-09T10:51:14.827Z",
  "account_id": "acc_12345",
  "data": {
    "lead_id": "lead_872c01",
    "phone_number": "971501234567",
    "name": "John Doe",
    "status": "New",
    "tags": [
      "website_inquiry",
      "vip"
    ]
  }
}

Lead Updated

CRM

Triggered when an existing lead's name, tags, or metadata are updated.

A sample payload for this event isn't published yet.

Order Received

Catalog

eventorder_received

Triggered when a WhatsApp Catalog order or checkout is completed by a customer.

{
  "event": "order_received",
  "timestamp": "2026-11-09T10:51:14.827Z",
  "account_id": "acc_12345",
  "data": {
    "order_id": "ord_9921b3",
    "customer": {
      "name": "Ali Ahmed",
      "phone": "971521345678"
    },
    "items": [
      {
        "product_id": "prod_1",
        "title": "Espresso Blend",
        "quantity": 2,
        "price": 45
      }
    ],
    "total": 90,
    "currency": "AED"
  }
}

Message Failed

Delivery

eventmessage_failed_response

Triggered when an outbound message fails Meta delivery or validation.

{
  "event": "message_failed_response",
  "timestamp": "2026-11-09T10:51:14.827Z",
  "account_id": "acc_12345",
  "data": {
    "message_id": "msg_1048f7",
    "recipient": "971501234567",
    "error_code": 131026,
    "error_message": "Message undeliverable: User is outside 24h conversation window."
  }
}

Message Status

Delivery

eventmessage_status

Triggered when an outbound message is sent, delivered, or read (data.status).

{
  "event": "message_status",
  "timestamp": "2026-11-09T10:51:14.827Z",
  "accountId": "acc_12345",
  "data": {
    "wamid": "wamid.HBgLM...",
    "messageId": "msg_1048f7",
    "status": "delivered",
    "recipient": "971501234567",
    "convoId": "convo_abc123",
    "timestamp": "1730707200"
  }
}

Inbound webhook URLs

Static URLs for receiving automated webhook notifications from external platforms. The URLs below are examples only: get your actual URLs from Inbound Webhook URLs in the WeTarseel app at app.wetarseel.ai.

Example URLs. webhooks.example.com and YOUR_WEBHOOK_TOKEN are placeholders. Copy your real URLs, with your account's host and token, from app.wetarseel.ai.

WooCommerce / CartFlows

POST

Paste this URL into your WooCommerce Webhook settings or the CartFlows Cart Abandonment plugin.

https://webhooks.example.com/woocommerce-webhook?token=YOUR_WEBHOOK_TOKEN

Blinko

POST

Paste this URL into your Blinko Webhook settings and configure the Bearer Authorization header.

https://webhooks.example.com/blinko-webhook

Authorization: Bearer YOUR_WEBHOOK_TOKEN

Treat these URLs and the token like a password: anyone who has them can send events into your account.