Documentation

Connecting Civagent to WhatsApp

Civagent can receive and answer WhatsApp messages using Meta’s Cloud API. You only need to paste your number details and point the Meta webhook to Civagent.

Overview

  • Link a WhatsApp Business number to your Civagent agent.
  • No code changes; just configure the webhook and tokens.
  • Supports message replies, button taps, and list selections.

What You’ll Need

  • A WhatsApp Business account with Cloud API access.
  • The Phone Number ID for your WhatsApp number.
  • An Access Token (system user or long-lived token).
  • The App Secret (for signature verification).
  • A Verify Token you choose (used once to confirm the webhook).
  • Access to your Civagent dashboard (Channels tab).

Step-by-Step Setup

  1. Open Civagent Channels
    In your agent’s dashboard, open Channels and choose WhatsApp.

  2. Add Number Details
    Enter the Phone Number ID, Access Token, App Secret, and the Verify Token you want to use. Save.

  3. Copy the Webhook URL
    Civagent shows a secure URL ending with /channels/whatsapp/{phoneNumberId}/webhook. Copy it.

  4. Set Webhook in Meta

    • Go to Meta Business → WhatsApp → Configuration.
    • Paste the Civagent URL into the Webhook field.
    • Enter the same Verify Token you set in Civagent. Submit and confirm the challenge.
    • Under Webhook fields, enable messages (and message_template_status if desired).

  5. Send a Test Message
    Use the Meta “Test” tool or send a real WhatsApp message to your number.

  6. Confirm in Civagent
    The channel will show as ready once the webhook is verified and the first message arrives.

How It Works (Plain English)

  • WhatsApp sends incoming messages to the Civagent webhook you configured.
  • Civagent checks the signature using your App Secret and the verify token from setup.
  • Civagent sends replies back through the WhatsApp Cloud Messages API to the same user.

Testing

  • Send “Hello” to your WhatsApp number.
  • You should see a reply within a few seconds.
  • If nothing comes back, re-check the Verify Token and make sure the webhook shows as “Active” in Meta.

Security & Compliance Notes

  • Webhooks are HMAC-verified with your App Secret; the verify token must match before activation.
  • Tokens stay within your Civagent project boundary; no data is used for training.
  • Conversation data remains within your WhatsApp Business account and Civagent workspace.

Troubleshooting

  • Webhook not verifying: the Verify Token in Meta must match exactly what you entered in Civagent.
  • Signature errors: confirm the App Secret and that https is used in the webhook URL.
  • No replies: check that the Access Token is current and that the number ID matches the URL.

Support

Need procurement-friendly language or a data flow diagram for Meta review? Your Civagent customer team can share a short security note and diagram on request.