> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osvi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Channel Variables

> Use the sender's WhatsApp number, name, or Instagram username in a chat agent's prompt and tools

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.

> [!NOTE]
>
> 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":

| Variable | Value | What it is |
| - | - | - |
| `whatsapp.phone_number` | `+919876543210` | Full international number (E.164). |
| `whatsapp.phone_national` | `9876543210` | The number without the country code. |
| `whatsapp.phone_digits` | `919876543210` | Country code and number, without the `+`. |
| `whatsapp.country_code` | `91` | The dialling code on its own. |
| `whatsapp.name` | `Riya Shah` | The sender's WhatsApp profile name. |
| `instagram.username` | `riya.shah` | The sender's Instagram handle, without the `@`. |
| `instagram.name` | `Riya Shah` | The sender's Instagram display name. |

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](https://docs.osvi.ai/platform/prompt-writing.md):

```jinja theme={null}
You are speaking with {{ whatsapp.name }}.
```

A variable can be empty (see [When a variable is empty](#when-a-variable-is-empty)), so guard anything the agent depends on:

```jinja theme={null}
{% if whatsapp.phone_number %}
The customer's number is {{ whatsapp.phone_number }}. Look up their booking before you reply.
{% else %}
Ask the customer for their phone number, email, or booking ID.
{% endif %}
```

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](https://docs.osvi.ai/platform/tools-custom.md), write the variable in the URL, a header, a query parameter, or the payload. Osvi fills it in when the tool runs.

```json theme={null}
{
  "phone": "{{whatsapp.phone_national}}",
  "booking_id": "{{booking_id}}"
}
```

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.

| Situation | Result |
| - | - |
| The conversation is on your website, in the app, or through the API | All channel variables are empty. |
| The agent is disconnected from the WhatsApp or Instagram channel | New conversations no longer arrive on that channel, so the variables are empty. |
| A WhatsApp conversation | `instagram.*` is empty. |
| An Instagram conversation | `whatsapp.*` is empty. |
| A WhatsApp sender whose number is hidden | The phone variables are empty. `whatsapp.name` is still filled. |
| An Instagram sender whose profile hasn't been read yet | `instagram.username` and `instagram.name` are empty for the first messages. |

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](https://docs.osvi.ai/platform/evals.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.