|
| 1 | +# WhatsApp Integration Setup Guide |
| 2 | + |
| 3 | +This guide describes how to configure Telecode to receive and reply to WhatsApp messages using either **Twilio Sandbox** (development mode) or **Meta Business API** (production mode). |
| 4 | + |
| 5 | +--- |
| 6 | + |
| 7 | +## 1. Choose a Provider |
| 8 | + |
| 9 | +| Provider | When to Use | Pros | Cons | |
| 10 | +|----------|--------------|------|------| |
| 11 | +| **Twilio (sandbox)** | Quick local testing, no app review required | Free sandbox number, easy webhook URL | Limited to sandbox participants, messages prefixed with `From` number must be added to sandbox contacts | |
| 12 | +| **Meta (Facebook) Business API** | Production deployment, official WhatsApp Business number | Full WhatsApp features, no message limits | Requires Facebook Business verification and app review | |
| 13 | + |
| 14 | +The provider is selected at runtime via the environment variable `WHATSAPP_MODE`: |
| 15 | + |
| 16 | +```bash |
| 17 | +# Twilio sandbox (default) |
| 18 | +export WHATSAPP_MODE=twilio |
| 19 | + |
| 20 | +# Meta Business API |
| 21 | +export WHATSAPP_MODE=meta |
| 22 | +``` |
| 23 | + |
| 24 | +Both providers share the same internal processing pipeline, so your bot behaviour is identical regardless of the source. |
| 25 | + |
| 26 | +--- |
| 27 | + |
| 28 | +## 2. Twilio Sandbox Setup |
| 29 | + |
| 30 | +1. **Create a Twilio account** – sign up at https://www.twilio.com/ and obtain a **Account SID** and **Auth Token**. |
| 31 | +2. **Enable the WhatsApp Sandbox** – in the Console navigate to **Messaging → Try it Out → WhatsApp Sandbox**. |
| 32 | +3. **Configure the sandbox**: |
| 33 | + - Note the sandbox phone number (e.g. `+14155238886`). |
| 34 | + - Add the shown **join code** to your personal WhatsApp number to join the sandbox. |
| 35 | +4. **Set the webhook URL**: |
| 36 | + - In the Sandbox settings, set the **WHEN A MESSAGE COMES IN** URL to `https://<your‑host>/webhook/whatsapp`. |
| 37 | + - If you are developing locally, expose the port with a tunnelling service such as **Cloudflare Tunnel** (recommended) or **ngrok**. |
| 38 | +5. **Expose the local FastAPI server**: |
| 39 | + ```bash |
| 40 | + # Example using Cloudflare Tunnel (install `cloudflared` first) |
| 41 | + cloudflared tunnel --url http://localhost:8000 |
| 42 | + ``` |
| 43 | + - Copy the generated public URL (e.g. `https://abcd1234.trycloudflare.com`) and use it as the webhook URL above. |
| 44 | +6. **Update `config.json`** with your Twilio credentials: |
| 45 | + ```json |
| 46 | + "twilio": { |
| 47 | + "account_sid": "YOUR_TWILIO_ACCOUNT_SID", |
| 48 | + "auth_token": "YOUR_TWILIO_AUTH_TOKEN", |
| 49 | + "sandbox_number": "+14155238886" |
| 50 | + } |
| 51 | + ``` |
| 52 | +7. **Run Telecode** (Docker example): |
| 53 | + ```bash |
| 54 | + docker run -p 8000:8000 \ |
| 55 | + -e WHATSAPP_MODE=twilio \ |
| 56 | + -e CONFIG_PATH=/app/config.json \ |
| 57 | + telecode |
| 58 | + ``` |
| 59 | + The service will listen on port **8000** for the `/webhook/whatsapp` POST endpoint. |
| 60 | + |
| 61 | +--- |
| 62 | + |
| 63 | +## 3. Meta Business API Setup |
| 64 | + |
| 65 | +1. **Create a Facebook Business Manager** account and a **WhatsApp Business Account**. |
| 66 | +2. **Create a WhatsApp Business App** in the Meta Developer portal. |
| 67 | +3. **Obtain credentials**: |
| 68 | + - **Phone Number ID** – the identifier for the WhatsApp number you have provisioned. |
| 69 | + - **Access Token** – a permanent page access token with `whatsapp_business_management` and `whatsapp_business_messaging` scopes. |
| 70 | + - **Verify Token** – any random string you will use to verify the webhook. |
| 71 | +4. **Set up the webhook** in the Meta App Dashboard: |
| 72 | + - Subscribe to the `messages` and `message_deliveries` fields. |
| 73 | + - Set the callback URL to `https://<your‑host>/webhook/whatsapp`. |
| 74 | + - Provide the **Verify Token** you defined in the previous step. |
| 75 | +5. **Expose the FastAPI server** (same as Twilio – Cloudflare Tunnel or ngrok) and point the Meta webhook URL to the public address. |
| 76 | +6. **Add credentials to `config.json`**: |
| 77 | + ```json |
| 78 | + "meta_whatsapp": { |
| 79 | + "phone_number_id": "YOUR_PHONE_NUMBER_ID", |
| 80 | + "access_token": "YOUR_ACCESS_TOKEN", |
| 81 | + "verify_token": "YOUR_VERIFY_TOKEN" |
| 82 | + } |
| 83 | + ``` |
| 84 | +7. **Run Telecode** (Docker example): |
| 85 | + ```bash |
| 86 | + docker run -p 8000:8000 \ |
| 87 | + -e WHATSAPP_MODE=meta \ |
| 88 | + -e CONFIG_PATH=/app/config.json \ |
| 89 | + telecode |
| 90 | + ``` |
| 91 | + Meta will perform a GET verification request; Telecode will automatically respond with the challenge token. |
| 92 | + |
| 93 | +--- |
| 94 | + |
| 95 | +## 4. Common Troubleshooting |
| 96 | + |
| 97 | +- **404 on webhook URL** – ensure the container’s port `8000` is exposed (`EXPOSE 8000` in Docker) and the host is reachable via the public tunnel. |
| 98 | +- **Invalid signature / token mismatch** – double‑check the `VERIFY_TOKEN` in `config.json` matches the token entered in the Meta dashboard. |
| 99 | +- **Twilio sandbox rejecting messages** – verify that the sandbox participant phone number has joined the sandbox using the provided join code. |
| 100 | +- **Permission errors** – the LLM/command pipeline may reject certain commands; check Telecode logs for `PermissionError` messages. |
| 101 | + |
| 102 | +--- |
| 103 | + |
| 104 | +You now have a fully functional WhatsApp endpoint for Telecode. Switch between providers simply by changing `WHATSAPP_MODE` and providing the appropriate credentials in `config.json`. |
0 commit comments