Skip to main content

​
Before you begin

You’ll need three things in place before making your first API call:
You need a Connectly business account and a business ID to scope your API requests. Your API key authenticates every request — contact your Account Manager if you don’t have one yet, or generate one from the Connectly Dashboard at any time.
Keep your API key secret. Never commit it to source control or expose it in client-side code. If a key is compromised, regenerate it immediately from the Dashboard.
You need a verified Facebook Business Manager account with admin access. Meta uses this to own and manage your WhatsApp Business Account, and to review and approve your message templates.
A WABA is required to send and receive WhatsApp messages as a business. Connectly is a WhatsApp BSP (Business Service Provider) and can onboard you directly from the Connectly inbox. To register a WABA you’ll need:
ResourcePurpose
Facebook PageRequired by Meta to link your business presence to your WABA.
Facebook Business ManagerWhere your WABA lives and your templates are managed.
Phone number (SMS or call capable)Used for one-time verification of your WhatsApp sender number.
Your Account Manager will walk you through the registration once these are in place.

​
Step 1: Authenticate your requests

Every Connectly API request must include your API key as an X-API-Key header. There are no session tokens or OAuth flows — just a single header on every call. 
curl --request POST \
  --url https://api.connectly.ai/v1/businesses/<business_id>/send/whatsapp_templated_messages \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <YOUR_KEY_HERE>' \
  --data '{}'
Any request missing a valid X-API-Key header returns an ERROR_TYPE_AUTHENTICATION error.

​
Step 2: Send a template message

Template messages are pre-approved message formats managed in your Facebook Business Manager. They are not subject to the 24-hour reply window — you can send them to any customer at any time, even if they have never messaged you before.
Your template must be created and approved in Facebook Business Manager before you can use it in an API call. Contact the Connectly team if you need help getting a template approved.
curl --request POST \
  --url https://api.connectly.ai/v1/businesses/<business_id>/send/whatsapp_templated_messages \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <YOUR_KEY_HERE>' \
  --data '{
    "number": "+1XXXXXXXXXX",
    "templateName": "your_template_name",
    "language": "en_US",
    "parameters": [
      { "name": "body_1", "value": "John" },
      { "name": "body_2", "value": "your order" }
    ]
  }'
Request fields
FieldTypeDescription
numberstringRecipient’s WhatsApp number in E.164 format (e.g. +1XXXXXXXXXX).
templateNamestringExact name of the approved template in your WhatsApp Manager.
languagestringLanguage code for the template translation (e.g. en_US, pt_BR, es).
parametersarrayName/value pairs that substitute variables in the template body, header, or buttons.
Response 
{ "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV" }
The id is your message ID. Use it to correlate delivery status events if you’re subscribed to webhooks.

​
Step 3: Reply with a session message

Once a customer messages you, a 24-hour session window opens. During that window you can send free-form session messages — no template or pre-approval needed.
If the customer hasn’t messaged you in the last 24 hours — or has never messaged you at all — you must use a template message instead. The session endpoint will return an error outside this window.
curl --request POST \
  --url https://api.connectly.ai/v1/businesses/<business_id>/send/messages \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <YOUR_KEY_HERE>' \
  --data '{
    "recipient": {
      "id": "+1XXXXXXXXXX",
      "channelType": "whatsapp"
    },
    "message": {
      "text": "Hello! How can we help you today?"
    }
  }'
Response 
{ "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV" }
Add an optional sender object ({ "id": "+14151111234", "channelType": "whatsapp" }) to choose which of your WhatsApp numbers sends the message. If omitted, Connectly uses your default number.

​
Which message type should I use?

SituationUse
First message to a customerTemplate message
Customer hasn’t replied in over 24 hoursTemplate message
Replying within the 24-hour windowSession message
Proactive notifications, campaigns, remindersTemplate message
Bulk send to many recipients at onceCampaigns API