> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Answers to the most common questions about the Connectly API — messaging, templates, webhooks, campaigns, and account setup 🙋‍♀️

## Messaging

<AccordionGroup>
  <Accordion title="What's the difference between /send/messages and /send/whatsapp_templated_messages?">
    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.
  </Accordion>

  <Accordion title="I'm getting ERROR_CODE_MESSAGE_OUTSIDE_OF_ELIGIBILITY_WINDOW — what do I do?">
    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.
  </Accordion>

  <Accordion title="I'm within the 24-hour window but still getting the eligibility error.">
    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:

    ```json theme={null}
    {
      "sender": {
        "id": "+11234567890",
        "channelType": "whatsapp"
      }
    }
    ```

    This ensures the message is sent from the correct number that has an open session with the customer.
  </Accordion>

  <Accordion title="How do I send from a specific number when I have multiple?">
    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:**

    ```json theme={null}
    {
      "sender": { "id": "+14151111234", "channelType": "whatsapp" },
      "recipient": { "id": "+16044441111", "channelType": "whatsapp" },
      "message": { "text": "Hello!" }
    }
    ```

    **Template message:**

    ```json theme={null}
    {
      "sender": "+14151111234",
      "number": "+16044441111",
      "templateName": "my_template",
      "language": "en",
      "parameters": []
    }
    ```
  </Accordion>

  <Accordion title="My template message is failing when I send to a business WhatsApp number.">
    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.
  </Accordion>

  <Accordion title="How do I track which webhook event belongs to which message I sent?">
    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.
  </Accordion>
</AccordionGroup>

***

## Templates

<AccordionGroup>
  <Accordion title="How long does template approval take?">
    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.
  </Accordion>

  <Accordion title="My template was rejected — what do I do?">
    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](https://developers.facebook.com/docs/whatsapp/message-templates/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.
  </Accordion>

  <Accordion title="Can I edit an existing template?">
    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.
  </Accordion>

  <Accordion title="Why is messagesLimitTier showing as UNSPECIFIED?">
    `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.
  </Accordion>
</AccordionGroup>

***

## Webhooks

<AccordionGroup>
  <Accordion title="How do I verify that a webhook payload came from Connectly?">
    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:

    ```go theme={null}
    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.
  </Accordion>

  <Accordion title="callbackData isn't appearing on some inbound replies — why?">
    `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.
  </Accordion>

  <Accordion title="Connectly isn't delivering events to my webhook endpoint — what should I check?">
    * 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).
  </Accordion>
</AccordionGroup>

***

## Campaigns

<AccordionGroup>
  <Accordion title="I'm getting a 409 error when triggering a campaign sendout — what does it mean?">
    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.
  </Accordion>

  <Accordion title="Can I send the same campaign to the same customer more than once?">
    By default, no — the API prevents duplicate sends. To override this, set `options.if_duplicate_check_unspecified` to `"allow_multiple"` in your request:

    ```json theme={null}
    {
      "options": {
        "if_duplicate_check_unspecified": "allow_multiple"
      },
      "entries": [...]
    }
    ```

    Use this only when repeated sends are intentional — for example, recurring service alerts.
  </Accordion>

  <Accordion title="How do I find my campaignName to use in the API?">
    In the Connectly inbox at [inbox.connectly.ai](https://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.
  </Accordion>
</AccordionGroup>

***

## Account & general

<AccordionGroup>
  <Accordion title="Where do I find my business ID?">
    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}/...`.
  </Accordion>

  <Accordion title="My API key stopped working — what do I do?">
    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.
  </Accordion>

  <Accordion title="I'm hitting rate limits — what are they?">
    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.
  </Accordion>

  <Accordion title="Can't figure it out?">
    Email us at [contact@connectly.ai](contact@connectly.ai) and include your `cntTraceId` from any error responses — it's the fastest way for our team to diagnose the issue.
  </Accordion>
</AccordionGroup>