Skip to content
Nappai Documentation

WhatsApp WebHook

The WhatsApp WebHook component lets you listen for messages that arrive on your Twilio WhatsApp number. Whenever someone sends a WhatsApp message, Twilio forwards the data to this component, which then makes the message text and any attached media available for use in your Nappai workflow.

How it Works

When you add the component to a dashboard, it registers a webhook URL with Twilio. Twilio calls that URL every time a new WhatsApp message is received. The component parses the incoming JSON payload, extracts the message text, sender information, and any media files, and then outputs this data so you can route it to other components (e.g., store it, trigger a response, or start a new process).

Inputs

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

  • Data: Use this field to quickly test the webhook component by providing a JSON payload that mimics what Twilio would send.
  • Store Messages: If checked, the component saves each incoming message to the workflow history so you can review or reference it later.
  • Credential: Select a previously configured Twilio WhatsApp Integration credential. This credential holds the Twilio Account SID, Auth Token, and Phone Number needed to authenticate with Twilio.
    1. First, create the credential in the Nappai credentials section.
    2. Then choose that credential in the component’s Credential field.

Outputs

  • Data: The raw JSON payload received from Twilio, useful for debugging or custom processing.
  • Message: The plain text of the WhatsApp message.
  • Media: Any media files (images, videos, documents) attached to the message, returned as binary data that can be passed to storage or other components.

Usage Example

  1. Set up the credential

    • Go to Credentials → Add Credential → Twilio WhatsApp Integration.
    • Enter your Twilio Account SID, Auth Token, and WhatsApp-enabled phone number.

  2. Add the component to a dashboard

    • Drag the WhatsApp WebHook component onto the canvas.
    • In the Credential field, select the credential you just created.
    • Check Store Messages if you want to keep a history.

  3. Connect outputs

    • Connect the Message output to a Text Display component to show the incoming text.
    • Connect the Media output to a File Storage component to save any attachments.

  4. Test

    • Send a WhatsApp message to your Twilio number.
    • The component receives the webhook, outputs the message and media, and stores the data if enabled.
  • TwilioWebhook – The base component that handles generic Twilio webhook events.
  • TwilioWebhookComponent – The underlying Python class that powers the WhatsApp WebHook component.

Tips and Best Practices

  • Use the Data input for quick testing: Paste a sample Twilio payload to verify the component’s parsing logic before deploying.
  • Enable Store Messages only when needed: Storing every message can quickly fill up history logs; enable it only if you need audit trails.
  • Keep credentials secure: Never expose your Twilio Auth Token or Account SID in public dashboards.
  • Check Twilio sandbox settings: If you’re using a sandbox number, remember that only approved phone numbers can send messages.

Security Considerations

  • Credentials are stored encrypted in Nappai; only users with permission can view or edit them.
  • The component transmits data over HTTPS to Twilio, ensuring encryption in transit.
  • If you expose the webhook URL publicly, consider adding a verification step (e.g., checking a signature header) to prevent spoofed requests.