Skip to main content

​
Messaging

Use /send/whatsapp_templated_messages to initiate a conversation — when the customer hasn’t messaged you before, or their 24-hour session window has expired. Templates are pre-approved by Meta and can be sent at any time.Use /send/messages to reply within an active session — the customer must have messaged you first within the last 24 hours. Session messages are free-form and don’t require pre-approval.See Messaging API overview for a full comparison table.
This error means the customer’s 24-hour session window has expired. You cannot send a session message to them. Switch to the Send template message endpoint instead — templates bypass the 24-hour restriction.
If you have multiple WhatsApp numbers registered with Connectly, our backend may be selecting a different number than the one the customer messaged. Specify the sender explicitly in your request:
{
  "sender": {
    "id": "+11234567890",
    "channelType": "whatsapp"
  }
}
This ensures the message is sent from the correct number that has an open session with the customer.
Include the optional sender object in your request body with your chosen phone number in E.164 format. This works on both the session message and template message endpoints:Session message:
{
  "sender": { "id": "+14151111234", "channelType": "whatsapp" },
  "recipient": { "id": "+16044441111", "channelType": "whatsapp" },
  "message": { "text": "Hello!" }
}
Template message:
{
  "sender": "+14151111234",
  "number": "+16044441111",
  "templateName": "my_template",
  "language": "en",
  "parameters": []
}
WhatsApp template messages can only be sent to personal WhatsApp accounts — not to WhatsApp API (business) accounts. When testing, use your personal WhatsApp phone number rather than a business number. Also make sure your personal account has accepted all WhatsApp app and privacy updates.
Use the callbackData field when sending a message. Set it to any JSON value up to 1024 bytes (e.g. { "order_id": "12345" }) and Connectly echoes it back in every related webhook event — delivery status updates and inbound replies that reference the message.Alternatively, save the id returned in the send response and match it against statusUpdate.id in delivery status webhook events.

​
Templates

Meta typically approves templates within 5 minutes, but it can take up to 24 hours. After submitting via Create template, poll Get templates periodically to check the status. The template starts as MESSAGE_TEMPLATE_STATUS_PENDING and transitions to approved or rejected.
Check the rejectionReason field in the Get templates response. Common reasons include:
  • INVALID_FORMAT — the template structure doesn’t meet Meta’s guidelines. Review Meta’s Message Template Guidelines.
  • Variables not numbered sequentially (e.g. using {{1}} and {{3}} without {{2}}).
  • Shortened URLs (e.g. bit.ly) in button fields — use the full URL.
  • Content that violates WhatsApp’s commerce or messaging policies.
Fix the issues and submit a new template. You cannot edit a rejected template — create a new one with a different name.
Meta only allows editing an approved template once within a 24-hour period, and only certain fields. For significant changes, it’s safer to create a new template with a different name, get it approved, and then delete the old one once it’s no longer in use.
WHATS_APP_MESSAGE_LIMIT_TIER_UNSPECIFIED is expected for new accounts or accounts whose tier hasn’t changed since setup. The field only updates when Meta registers a tier change. This is not an error — your account can still send messages. Check Get quality signals again after sending your first batch of campaigns.

​
Webhooks

Every webhook request Connectly sends includes an x-connectly-hmac-sha256 header — a Base64-encoded HMAC-SHA256 digest of the raw request body, signed with your webhook secret. Verify it before processing:
secret := "YOUR_SECRET_VALUE"
hash := hmac.New(sha256.New, []byte(secret))
hash.Write(webhookEventBody)
isValid := webhookEventHMAC == base64.StdEncoding.EncodeToString(hash.Sum(nil))
Reject any request where the HMAC doesn’t match. See Webhooks overview for more detail.
callbackData is only echoed back on webhook events that are directly linked to the original outbound message:
  • Delivery status events (sent, delivered, read, delivery_failed) — always included.
  • Inbound replies that quote the original message — button replies, list replies, quoted media, reactions.
Plain-text replies that don’t quote the original message do not include callbackData — WhatsApp provides no server-side signal linking them to a specific outbound message.
  • Your endpoint must be publicly accessible over HTTPS. Plain HTTP endpoints are not supported.
  • Your endpoint must return a 2xx response within a reasonable timeout. Connectly treats non-2xx responses as failures.
  • Confirm your webhook registration is active using Get webhooks.
  • Check that you registered for the correct topic (messages for inbound, delivery_status for outbound delivery events).

​
Campaigns

A 409 means the campaign is not in a state that accepts sendouts — typically because it hasn’t been published yet. Go to the Connectly Flow Builder, finalize and publish the campaign, then retry the API call.
By default, no — the API prevents duplicate sends. To override this, set options.if_duplicate_check_unspecified to "allow_multiple" in your request:
{
  "options": {
    "if_duplicate_check_unspecified": "allow_multiple"
  },
  "entries": [...]
}
Use this only when repeated sends are intentional — for example, recurring service alerts.
In the Connectly inbox at inbox.connectly.ai, go to the Flow Builder, select Resend or Edit next to your campaign, and copy the name exactly as shown. See Campaigns overview for a step-by-step guide.

​
Account & general

Your business ID is a UUID that scopes all your API requests. You can find it in the Connectly Dashboard under your account settings, or ask your Connectly Account Manager. It appears in the path of every API endpoint: /v1/businesses/{businessId}/....
API keys can be regenerated at any time from the Connectly Dashboard under Settings → General → API Key. Note that the plaintext key is only shown once when created — if you’ve lost it, you’ll need to create a new one. Update your backend configuration with the new key immediately, as the old one will no longer authenticate.
Most messaging endpoints are limited to 200 requests per second with burst capacity up to 1,000 requests per second. The Assets API is limited to 100 requests per second. Exceeding these limits returns 429 Too Many Requests. Implement exponential backoff in your client if you expect sustained high volume.
Email us at contact@connectly.ai and include your cntTraceId from any error responses — it’s the fastest way for our team to diagnose the issue.