Skip to main content
When a customer messages a chat agent on WhatsApp or Instagram, the conversation starts with their message. Nothing calls your API first, so there are no input fields carrying their phone number or name. Channel variables fill that gap. They hold what Meta tells us about the sender, and you can use them anywhere a prompt or a custom tool accepts a variable.
Channel variables work for chat agents. Voice agents on WhatsApp Calling don’t have them yet.

The variables

For a sender on WhatsApp number +91 98765 43210 with the profile name “Riya Shah”: Pick the phone format your API expects. phone_national is the right choice for a system that stores 10-digit Indian numbers, but its length depends on the country: a UAE mobile has 9 digits there. If you have international customers, match on phone_number or phone_digits.

Using them in a prompt

Write the variable in double curly braces, as with any other prompt variable:
A variable can be empty (see When a variable is empty), so guard anything the agent depends on:
The agent only sees a channel variable where you write it. Nothing about the sender is added to the prompt on its own.

Using them in a custom tool

In a custom tool, write the variable in the URL, a header, a query parameter, or the payload. Osvi fills it in when the tool runs.
Here booking_id is a parameter the agent fills in, and phone is filled by Osvi. Do not declare the phone as a tool parameter. The agent never has to find or repeat the number, so the lookup works from the customer’s first message. If a tool declares its own parameter named whatsapp or instagram, that parameter is used instead.

When a variable is empty

An empty variable is replaced with nothing. Your API receives "", never the placeholder text. Because one agent can serve several channels, write the prompt so it works either way, using the {% if %} guard above.

Testing

The playground and evals don’t run on WhatsApp or Instagram, so the variables are empty there unless you fill them in. In the playground, use Add input fields: the channel variables your prompt uses appear in the list. Enter a whatsapp.phone_number and the other phone formats are worked out from it. On a real WhatsApp or Instagram conversation, values you pass in yourself under these names are ignored. Only what Meta reports is used.