WhatsApp

Jelliu agents answer and start conversations on WhatsApp Business. The channel runs on the WhatsApp Business Platform through Twilio, with one sender (a business phone number) per workspace. Everything a contact writes to that number is routed to one of your agents, and everything you send goes through the same compliance, opt-out and quota checks as the rest of the platform.

This page covers the API surface: senders, templates, sending, what happens to inbound messages, and the limits that apply.

How it works

Three rules shape every integration:

1. Nothing is sent without an ONLINE sender. Sends from a workspace whose number is still being approved, or is offline, are refused with an explanation.
2. Meta’s 24-hour customer-care window decides the message form. Freeform text is allowed only if the contact wrote to your number in the last 24 hours. Outside that window only an approved template can be sent.
3. An opt-out is final. When a contact asks to stop, Jelliu suppresses the number and sends nothing more, not even a confirmation.

Senders

A sender is the WhatsApp Business phone number your workspace messages from. Replies are sent from the line the contact last wrote to, when that line is still online; otherwise from your most recently updated online sender.

Endpoints

Every response wraps the result in data. DELETE returns 204 with no body.

Sender lifecycle

Twilio does not push sender status changes, so Jelliu polls them about every two minutes and also re-checks senders that are already ONLINE, because Meta can take a number offline for quality reasons. Call POST /api/whatsapp-senders/{senderId}/refresh to re-read the status immediately.

The sender object

Register a number

curl -sS -X POST "https://api.jelliu.co/api/whatsapp-senders" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+573001234567",
    "verificationMethod": "sms",
    "displayName": "Clínica Norte",
    "vertical": "Medical and Health",
    "website": "https://clinicanorte.example.com"
  }'

curl -sS -X POST "https://api.jelliu.co/api/whatsapp-senders/$SENDER_ID/verify" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "482913" }'

Claim an existing sender

If a number is already registered as a WhatsApp sender with the provider, POST /api/whatsapp-senders/adopt with { "phoneNumber": "+573001234567" } binds it to your workspace. GET /api/whatsapp-senders/adoptable lists candidates. The number must already be an active number of your workspace; otherwise the claim is refused with 403: +573001234567 is not one of this account's numbers, so it cannot be claimed as a WhatsApp sender.

Update and remove

PATCH /api/whatsapp-senders/{senderId} accepts any of the profile fields above (at least one). It fails with 400 while the sender is not yet registered with the provider.

DELETE /api/whatsapp-senders/{senderId} removes the sender at the provider first. If the provider refuses, nothing is changed and you can retry.

Templates

A template is a message Meta has approved in advance. It is the only way to write to someone who has not messaged your number in the last 24 hours, and it also works inside the window.

Endpoints

Categories

Approval states

Approval results are polled from the provider about every two minutes, including for templates already approved, because Meta can pause or disable them later. POST /api/whatsapp-templates/{templateId}/refresh re-reads the state on demand.

The template object

Variables

Placeholders are written {{1}}, {{2}} and so on. variables declares one label per placeholder, so a body with two placeholders needs exactly two labels. Before a template is created, edited or submitted, Jelliu checks the body against the rules Meta rejects on, so you find out in seconds rather than after days of review:

• numbering starts at {{1}} and has no gaps;
• the body is not only a placeholder;
• two placeholders are never adjacent ({{1}} {{2}});
• the body does not start or end with a placeholder;
• the number of labels matches the number of placeholders.

A body that breaks a rule is refused with 400 and code VALIDATION_FAILED, and the message names the rule, in Spanish. For example:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "WhatsApp rechazaria esta plantilla: El mensaje no puede TERMINAR con una variable: pon texto después de la última variable."
  }
}

Create, submit and preview a template

curl -sS -X POST "https://api.jelliu.co/api/whatsapp-templates" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "recordatorio_cita",
    "friendlyName": "Recordatorio de cita",
    "language": "es",
    "category": "UTILITY",
    "bodyText": "Hola {{1}}, te recordamos tu cita del {{2}} en Clínica Norte. Responde a este mensaje si necesitas cambiarla.",
    "variables": ["nombre", "fecha"]
  }'

curl -sS -X POST "https://api.jelliu.co/api/whatsapp-templates/$TEMPLATE_ID/preview" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "variables": ["Ana", "viernes 19 a las 10:00"] }'

{
  "data": {
    "templateId": "3f1c9a52-7b0e-4d3a-9c21-5e8f7a6b4d10",
    "name": "recordatorio_cita",
    "language": "es",
    "bodyText": "Hola {{1}}, te recordamos tu cita del {{2}} en Clínica Norte. Responde a este mensaje si necesitas cambiarla.",
    "rendered": "Hola Ana, te recordamos tu cita del viernes 19 a las 10:00 en Clínica Norte. Responde a este mensaje si necesitas cambiarla.",
    "variableCount": 2,
    "resolvedValues": { "1": "Ana", "2": "viernes 19 a las 10:00" },
    "warnings": []
  }
}

curl -sS -X POST "https://api.jelliu.co/api/whatsapp-templates/$TEMPLATE_ID/submit" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

Test sends

POST /api/whatsapp-templates/{templateId}/test-send sends an approved template to any E.164 number so you can see it on a real phone, without creating a contact:

{ "toNumber": "+573001112233", "variables": ["Ana", "viernes 19 a las 10:00"] }

It returns 202 with messageSid, status, to, from and rendered.

Deleting templates

DELETE /api/whatsapp-templates/{templateId} removes the template at the provider and in Jelliu. A deleted template’s name stays reserved for that language: creating another template with the same name and language fails with 409.

Sending messages

Two endpoints send to a contact. Both take a contactId (the contact must have a WhatsApp number and belong to your workspace), both accept a write key, and both run the same checks.

POST /api/whatsapp/send

Provide message or templateId. Neither returns 400: Provide either a message or a templateId.

curl -sS -X POST "https://api.jelliu.co/api/whatsapp/send" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "templateId": "3f1c9a52-7b0e-4d3a-9c21-5e8f7a6b4d10",
    "templateVariables": ["Ana", "viernes 19 a las 10:00"]
  }'

{
  "data": {
    "messageSid": "SM2a4c6e8f0a1b3c5d7e9f1a2b3c4d5e6f",
    "status": "queued"
  }
}

POST /api/whatsapp/reach

• Window open: message is sent as freeform text and data.form is freeform.
• Window closed: your newest approved template in language is sent instead and data.form is template. Your text is not delivered; the template opens the conversation, and once the contact replies the window is open again.
• Window closed and no approved template in that language: nothing is sent, and the call fails with 422 NO_TEMPLATE_AVAILABLE.

{
  "data": {
    "messageSid": "SM9b8a7c6d5e4f3a2b1c0d9e8f7a6b5c4d",
    "status": "queued",
    "form": "template",
    "note": "WhatsApp only allows an approved template until the person writes to the line first, so an opening message was sent — NOT the material. Tell the person exactly that: you just wrote to them on WhatsApp, and if they reply there you will send the whole thing. Do not claim the information itself has been sent."
  }
}

note is written for an AI agent to relay to the contact. Branch on form in your own code.

Checks before every send

Both endpoints run these checks in order. A failure stops the send before any quota is used.

1. The contact exists in your workspace and has a WhatsApp number.
2. Compliance. The number is checked against your compliance rules: allowed contact hours for the contact’s country, blocked prefixes, the suppression list, do-not-call status, and the daily and total attempt limits.
3. Opt-out. A contact with status dnc or an opt-out date cannot be messaged.
4. Message form. A template must exist, be approved and be ready at the provider; freeform requires the 24-hour window.
5. Daily cap. One unit of the workspace’s daily WhatsApp cap is consumed. It is refunded if the send then fails.
6. Sender. An ONLINE sender must exist.

WhatsApp campaigns

A campaign with channel set to whatsapp writes first to every contact with the campaign’s approved template. Set whatsappTemplateId, whatsappTemplateVariables (literal values) and whatsappTemplateVariableMap (per-contact values such as {"1": "contact.first_name"}) on the campaign. Activation is refused if the template is not approved or a placeholder has no value source. Sends are paced at roughly one every 1.5 seconds per worker, and the last 20% of the daily cap (at least 25 messages) is reserved for replies so a campaign cannot leave your agent unable to answer. See Campaigns.

Inbound messages

When a contact writes to one of your numbers, Jelliu:

1. Routes by the receiving number. The number must belong to exactly one workspace with an ONLINE sender or an active phone number. Messages to numbers that are unknown, or claimed by more than one workspace, are dropped.
2. Checks for an opt-out before anything else (see below).
3. Finds the contact. It matches the sender’s number against contacts’ WhatsApp and phone numbers, preferring a contact in an active campaign, then a paused one, then a completed one. People who are not in any campaign are welcome: Jelliu creates a contact for them, unless the number is on the suppression list.
4. Picks the agent. The campaign’s agent if it serves WhatsApp; otherwise the agent bound to the receiving number; otherwise the workspace’s oldest agent that serves WhatsApp.
5. Opens the 24-hour window for that contact.
6. Generates and sends the reply in the background. If the agent has a response delay or human pacing configured, the reply waits, and several messages sent in a row are answered together.

Voice notes are transcribed and answered; the reply to a voice note includes a spoken version when it is short enough (600 characters or less), and the text is always sent too. Photos and PDFs sent with or without a caption reach the agent together with the caption.

Inbound conversations and their messages are available through Conversations.

Opt-out

A message is treated as an opt-out when the whole message is one of these keywords (case, extra spaces and trailing punctuation are ignored):

stop, stopall, stop all, cancel, unsubscribe, quit, end, baja, cancelar, darme de baja, dar de baja, no molestar

Longer phrasings such as “no me vuelvas a escribir” are also detected. Keywords inside a sentence are not: “quiero cancelar mi cita” is a request to reschedule, and the agent answers it. Voice notes are checked after transcription.

When an opt-out is detected, Jelliu:

• sets every contact in your workspace with that number to dnc and records the date and the matched keyword;
• adds the number to the workspace’s suppression list, which survives deleting and re-importing the contact;
• sends nothing back, not even a confirmation.

From then on, every send to that number fails with 403 CONTACT_OPTED_OUT or 423 COMPLIANCE_BLOCKED, and inbound messages from it are not answered. See Compliance to review or lift a suppression.

Delivery statuses

Jelliu subscribes to the provider’s delivery callbacks for every message it sends and records the latest status per message. Statuses only move forward: a late failed never overwrites a message already recorded as delivered or read.

The status in a send response is the status at the moment of sending, usually queued.

Errors

Send errors from /api/whatsapp/send and /api/whatsapp/reach use the standard envelope with a WhatsApp-specific code:

{
  "error": {
    "code": "OUTSIDE_24H_WINDOW",
    "message": "Outside the 24-hour window: this contact has not messaged you in the last 24h, so Meta requires an approved template to reach them. Pick a template to send."
  }
}

Sender and template endpoints return the generic codes from Errors: VALIDATION_FAILED (400, or 409 for duplicates such as +573001234567 is already registered as a WhatsApp sender.), FORBIDDEN, NOT_FOUND and RATE_LIMIT_EXCEEDED. A test send over its daily cap returns 429 RATE_LIMIT_EXCEEDED with a Spanish message such as Ya enviaste 3 pruebas de esta plantilla hoy. Cada prueba es un mensaje real que WhatsApp factura; intentalo manana.

Limits

Monthly AI message allowance

AI replies on WhatsApp, email, web chat, Instagram and Messenger share one monthly allowance per plan:

When the allowance is used up, or the workspace has no active plan, AI replies stop with 403 BILLING_ERROR, for example Llegaste al límite mensual de mensajes de IA (1200 mensajes del plan starter). Sube de plan en Ajustes → Plan. Messages you send yourself through /api/whatsapp/send are limited by the daily cap, not by this allowance. See Billing and usage.

Scopes at a glance

Related