Quick Start

Before you begin

You’ll need three things in place before making your first API call:

Connectly account & API key

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.

Facebook Business Manager

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.

WhatsApp Business Account (WABA)

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:

Resource	Purpose
Facebook Page	Required by Meta to link your business presence to your WABA.
Facebook Business Manager	Where 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 '{}'

import requests
 
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "<YOUR_KEY_HERE>"
}
 
response = requests.post(
    "https://api.connectly.ai/v1/businesses/<business_id>/send/whatsapp_templated_messages",
    headers=headers,
    json={}
)

const axios = require('axios');
 
const headers = {
    "Content-Type": "application/json",
    "X-API-Key": "<YOUR_KEY_HERE>"
};
 
axios.post(
    "https://api.connectly.ai/v1/businesses/<business_id>/send/whatsapp_templated_messages",
    {},
    { headers }
);

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

import requests
 
payload = {
    "number": "+1XXXXXXXXXX",
    "templateName": "your_template_name",
    "language": "en_US",
    "parameters": [
        { "name": "body_1", "value": "John" },
        { "name": "body_2", "value": "your order" }
    ]
}
 
response = requests.post(
    "https://api.connectly.ai/v1/businesses/<business_id>/send/whatsapp_templated_messages",
    headers={ "Content-Type": "application/json", "X-API-Key": "<YOUR_KEY_HERE>" },
    json=payload
)
print(response.json())

const axios = require('axios');
 
const payload = {
  number: "+1XXXXXXXXXX",
  templateName: "your_template_name",
  language: "en_US",
  parameters: [
    { name: "body_1", value: "John" },
    { name: "body_2", value: "your order" }
  ]
};
 
axios.post(
  "https://api.connectly.ai/v1/businesses/<business_id>/send/whatsapp_templated_messages",
  payload,
  { headers: { "Content-Type": "application/json", "X-API-Key": "<YOUR_KEY_HERE>" } }
).then(r => console.log(r.data));

Request fields

Field	Type	Description
`number`	string	Recipient’s WhatsApp number in E.164 format (e.g. `+1XXXXXXXXXX`).
`templateName`	string	Exact name of the approved template in your WhatsApp Manager.
`language`	string	Language code for the template translation (e.g. `en_US`, `pt_BR`, `es`).
`parameters`	array	Name/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?"
    }
  }'

import requests
 
payload = {
    "recipient": {
        "id": "+1XXXXXXXXXX",
        "channelType": "whatsapp"
    },
    "message": {
        "text": "Hello! How can we help you today?"
    }
}
 
response = requests.post(
    "https://api.connectly.ai/v1/businesses/<business_id>/send/messages",
    headers={ "Content-Type": "application/json", "X-API-Key": "<YOUR_KEY_HERE>" },
    json=payload
)
print(response.json())

const axios = require('axios');
 
const payload = {
  recipient: { id: "+1XXXXXXXXXX", channelType: "whatsapp" },
  message: { text: "Hello! How can we help you today?" }
};
 
axios.post(
  "https://api.connectly.ai/v1/businesses/<business_id>/send/messages",
  payload,
  { headers: { "Content-Type": "application/json", "X-API-Key": "<YOUR_KEY_HERE>" } }
).then(r => console.log(r.data));

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?

Situation	Use
First message to a customer	Template message
Customer hasn’t replied in over 24 hours	Template message
Replying within the 24-hour window	Session message
Proactive notifications, campaigns, reminders	Template message
Bulk send to many recipients at once	Campaigns API

Get Started

Campaigns

Messaging

Webhooks

Assets

AI Features

Analytics

Business Management

Integrations

Resources

Before you begin

Step 1: Authenticate your requests

Step 2: Send a template message

Step 3: Reply with a session message

Which message type should I use?

​Before you begin

​Step 1: Authenticate your requests

​Step 2: Send a template message

​Step 3: Reply with a session message

​Which message type should I use?

Before you begin

Step 1: Authenticate your requests

Step 2: Send a template message

Step 3: Reply with a session message

Which message type should I use?