Twilio WhatsApp

Twilio WhatsApp is a simple way to send, receive, list, and delete WhatsApp messages directly from your Nappai dashboard. It lets you send text, images, audio, documents, or videos, and it can also pull message history or remove old messages. The component works with a Twilio WhatsApp Integration credential that you set up once in Nappai’s credentials section.

How it Works

When you use the component, Nappai talks to Twilio’s WhatsApp API.

Send Message – Nappai posts a new message to the Twilio endpoint, optionally attaching a media file via a public URL.
Fetch Message – Nappai requests a single message’s details by its unique SID.
List Messages – Nappai pulls a list of messages, with optional filters for sender, recipient, inbound‑only, and page size.
Delete Message – Nappai deletes a message identified by its SID.

All communication is done over HTTPS, so your data stays secure while in transit. The component can also act as a “tool” for an AI agent, exposing the same operations as a callable function.

Operations

This component offers several operations that you can select based on what you need to do. You can only use one operation at a time:

Send Message: Send a new WhatsApp message (text, media, or both).
Fetch Message: Retrieve the details of a single message using its SID.
List Messages: Get a list of messages, optionally filtered by sender, recipient, inbound status, or page size.
Delete Message: Remove a message from Twilio using its SID.

To use the component, first select the operation you need in the Operation field.

Inputs

Mapping Mode

This component has a special mode called “Mapping Mode”. When you enable this mode using the toggle switch, an additional input called Mapping Data is activated, and each input field offers you three different ways to provide data:

Fixed: You type the value directly into the field.
Mapped: You connect the output of another component to use its result as the value.
Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Input Fields

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

Operation: Choose what you want to do: send a new message, fetch an existing one, or list messages.
- Visible in: Send Message, Fetch Message, List Messages, Delete Message
Message: Text content of the message.
- Visible in: Send Message
Filter: From (optional): Filter List Messages by exact sender (e.g. whatsapp:+14155238886).
- Visible in: List Messages
Filter: To (optional): Filter List Messages by exact recipient (e.g. whatsapp:+521XXXXXXXXXX).
- Visible in: List Messages
Mapping Mode: Enable mapping mode to process multiple data records in batch.
- Visible in: Send Message, Fetch Message, List Messages, Delete Message
Message SID: The unique SID of a message for Fetch Message (e.g. SMxxxxxxxxxxxxxxxxxxxxxxxxxxxx).
- Visible in: Fetch Message
Message SID to Delete: SID of the message to delete.
- Visible in: Delete Message
Only inbound?: If enabled, List Messages will return only inbound (received) messages.
- Visible in: List Messages
Page Size: Number of messages to list (1–1000). Default is 50.
- Visible in: List Messages
Silent Errors: If enabled, errors will be logged but won’t raise exceptions.
- Visible in: Send Message
Type Operation: Choose the type of operation: send a new message.
- Visible in: Send Message
Media URL: Public URL of the media file to send (image, audio, video, etc). Optional.
- Visible in: Send Message
Tool Name: The name of the tool that will be used when this component is connected as a tool. This name will be displayed to the agent when it selects tools to use.
- Visible in: Send Message, Fetch Message, List Messages, Delete Message
Tool Description: A detailed description of what this tool does. This description will help the agent understand when and how to use this tool effectively.
- Visible in: Send Message, Fetch Message, List Messages, Delete Message
Tools arguments metadata: Defines the arguments metadata for the tools.
- Visible in: Send Message, Fetch Message, List Messages, Delete Message

Credential
This component requires a Twilio WhatsApp Integration credential.

In Nappai, go to Credentials and create a new credential of type Twilio WhatsApp Integration.

Enter your Twilio Account SID, Auth Token, and Twilio Phone Number.

In the component, select this credential in the Credential field.
(The credential fields themselves are not listed here because they are handled separately.)

Outputs

Data: The raw data returned from Twilio (e.g., message details, list of messages).
Tool: A tool representation that can be used by an AI agent to call the selected operation.

Usage Example

Scenario: Send a welcome message with a promotional image to a new customer.

Drag the Twilio WhatsApp component onto your workflow.
Set Operation to Send Message.
In Message, type: “Welcome to our service! Enjoy this special offer.”
In Media URL, paste the public link to your promotional image.
Choose the Twilio WhatsApp Integration credential you created earlier.
Run the workflow. The component will send the message via Twilio and return the message SID in the Data output.

Scenario: List the last 20 inbound messages from a specific customer.

Set Operation to List Messages.
In Only inbound?, check the box.
In Filter: From, enter the customer’s WhatsApp number (e.g., whatsapp:+521123456789).
In Page Size, enter 20.
Run the workflow. The component will return a list of messages in the Data output.

Twilio SMS – Send and manage SMS messages via Twilio.
Twilio Voice – Make and receive voice calls with Twilio.
Email Sender – Send emails through integrated email services.

Tips and Best Practices

Batch Sending: Enable Mapping Mode and connect a list of phone numbers to send the same message to many recipients at once.
Error Handling: Turn on Silent Errors if you want the workflow to continue even if a message fails to send.
Media Size Limits: Twilio imposes limits on media file sizes (generally 5 MB for images, 100 MB for videos). Keep your URLs within these limits.
Use Tool Mode: When integrating with an AI agent, expose the component as a tool so the agent can decide when to send or fetch messages.
Secure Credentials: Store your Twilio credentials in Nappai’s credential store; never hard‑code them in the workflow.

Security Considerations

All communication with Twilio is encrypted over HTTPS.
Store your Twilio Account SID, Auth Token, and Phone Number in Nappai’s secure credential store.
Avoid exposing message SIDs or media URLs in public logs.
Use Silent Errors sparingly; while it prevents workflow crashes, it may hide important failures.