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

# Connect Twilio to Your Soneka Workspace for WhatsApp

> Link your existing Twilio WhatsApp number to Soneka in about two minutes. Supports both Twilio Sandbox for testing and production WhatsApp numbers.

If your business already uses Twilio for communications or you have an existing WhatsApp-enabled Twilio number, connecting it to Soneka takes about two minutes. You'll paste your Twilio credentials into Soneka and immediately gain access to the shared inbox, broadcast tools, and automation flows — all routed through your Twilio number. Both the Twilio Sandbox (for development and testing) and live production numbers are supported.

## Prerequisites

<CardGroup cols={2}>
  <Card title="Twilio Account" icon="server">
    An active Twilio account with billing enabled. Sign up at [twilio.com](https://www.twilio.com) if you don't have one.
  </Card>

  <Card title="WhatsApp-Enabled Number" icon="whatsapp">
    Either a Twilio production WhatsApp number (approved by Meta via Twilio) or access to the **Twilio Sandbox for WhatsApp** for testing.
  </Card>
</CardGroup>

## Find Your Twilio Credentials

You'll need two values from the Twilio Console: your **Account SID** and your **Auth Token**.

<Steps>
  <Step title="Log in to Twilio Console">
    Go to [console.twilio.com](https://console.twilio.com) and sign in. Your **Account SID** and **Auth Token** are displayed on the main dashboard under **Account Info**.
  </Step>

  <Step title="Copy Account SID">
    Click the copy icon next to your Account SID. It starts with `AC` followed by a 32-character string.
  </Step>

  <Step title="Reveal and Copy Auth Token">
    Click the eye icon to reveal your Auth Token, then copy it. Keep this value private — it grants full access to your Twilio account.
  </Step>
</Steps>

<Warning>
  Never share your Auth Token publicly or commit it to source control. If it's ever exposed, rotate it immediately in Twilio Console under **API Keys & Tokens**.
</Warning>

## Enter Credentials in Soneka

<Steps>
  <Step title="Open Integrations">
    In Soneka, go to **Settings → Integrations → Twilio** and click **Connect**.
  </Step>

  <Step title="Paste Your Credentials">
    Enter your **Account SID** and **Auth Token** into the respective fields.
  </Step>

  <Step title="Select Sandbox or Production">
    Choose your connection mode (see below). Then click **Save & Connect**. Soneka will verify the credentials with Twilio's API before activating.
  </Step>
</Steps>

## Sandbox vs. Production

<Tabs>
  <Tab title="Sandbox (Testing)">
    The Twilio Sandbox lets you test WhatsApp messaging without a Meta-approved number. Recipients must first opt in by sending a specific join code to the Twilio Sandbox number.

    **To use Sandbox mode:**

    * Select **Sandbox** when entering credentials in Soneka.
    * Share the sandbox join instructions with your test contacts (found in Twilio Console → Messaging → Try it out → Send a WhatsApp message).
    * Messages sent and received will appear in the Soneka inbox under the Sandbox channel.

    <Note>
      Sandbox numbers cannot send template (HSM) messages. Use Sandbox only for development and functional testing.
    </Note>
  </Tab>

  <Tab title="Production">
    A production Twilio WhatsApp number has been approved by Meta via Twilio's onboarding process. It can send template messages and engage in real customer conversations.

    **To use Production mode:**

    * Select **Production** when entering credentials in Soneka.
    * Enter the production WhatsApp-enabled number in E.164 format (e.g., `+14155238886`).
    * Ensure the number's webhook URL is managed by Soneka (Soneka sets this automatically on connect).
  </Tab>
</Tabs>

## Switching Between Sandbox and Production

To switch modes after initial setup, go to **Settings → Integrations → Twilio → Edit Connection**, change the mode, and click **Save**. Soneka will re-verify the credentials and update the Twilio webhook configuration automatically. Existing conversation history is preserved.

## Limitations vs. WhatsApp Cloud API

While Twilio is a solid choice if you're already invested in its ecosystem, there are some differences to keep in mind:

| Feature                  | Twilio                        | WhatsApp Cloud API            |
| ------------------------ | ----------------------------- | ----------------------------- |
| Setup time               | \~2 min                       | \~4 min                       |
| Green tick eligibility   | ❌                             | ✅                             |
| Template message support | Production only               | ✅                             |
| Messaging rate limits    | Twilio-set limits             | Meta tiered (up to unlimited) |
| Pricing                  | Twilio per-message fees apply | Meta conversation-based fees  |
| Sandbox for testing      | ✅                             | ❌                             |

<Tip>
  If you're starting fresh, we recommend the **WhatsApp Cloud API** for production use — it's the official Meta channel, offers higher rate limits, and doesn't incur additional per-message fees from Twilio.
</Tip>

## Troubleshooting

<Accordion title="'Authentication failed' when saving credentials">
  Double-check that you copied the Account SID and Auth Token exactly, with no leading or trailing spaces. Also confirm you're using your primary account credentials, not a sub-account.
</Accordion>

<Accordion title="Messages sent from Soneka aren't delivered">
  Verify that the phone number entered in Soneka exactly matches the WhatsApp-enabled number in your Twilio account (in E.164 format). Also check Twilio's error logs in Console → Monitor → Logs → Errors for delivery failure codes.
</Accordion>

<Accordion title="Incoming messages not appearing in Soneka inbox">
  Soneka automatically configures your Twilio webhook on connect. If inbound messages aren't appearing, go to **Twilio Console → Messaging → Senders → WhatsApp Senders**, select your number, and confirm the Webhook URL matches the one shown in **Soneka → Settings → Integrations → Twilio → Webhook Info**.
</Accordion>

<Accordion title="Sandbox opt-in message not working">
  Each test contact must send the exact join keyword to the Twilio Sandbox number before they can receive messages. The keyword is shown in Twilio Console. If they've already joined previously, their opt-in may have expired — have them re-send the join message.
</Accordion>