Build a WhatsApp Agent with Zero Runtime

Architecture

A WhatsApp caller reaches the Meta Business Platform, which forwards the call over SIP to the Zero Runtime SIP Gateway. A routing rule invokes your self-hosted agent by matching its agent_id.

Prerequisites

Meta side:
- A verified Meta Business Manager account.
- A phone number verified in your WhatsApp Business Account (WABA).
- A Meta Developer App with the whatsapp_business_management permission enabled.
- A permanent user access token for the Meta Graph API.
Zero Runtime side: A ZRT Auth token (ZRT_AUTH_TOKEN). Generate one in the Zero Runtime Dashboard.

Setup the project

Use Python 3.11 or higher, then install the Zero Runtime Agents SDK. Create and activate a virtual environment, then install zrt and python-dotenv. Every provider plugin ships with zrt.

uv venv --python 3.11
source .venv/bin/activate     # macOS/Linux
.\.venv\Scripts\activate      # Windows

python3.11 -m venv venv
source venv/bin/activate      # macOS/Linux
.\venv\Scripts\activate       # Windows

New to uv? See the uv install guide.

uv pip install zrt python-dotenv

pip install zrt python-dotenv

Configure environment variables

Store API keys and tokens in a .env file in your project root.

Cascade
Realtime

.env

# The Inference gateway authenticates with your Zero Runtime token -
# no separate STT, LLM, or TTS provider keys needed.

# Option A: pre-generated token
ZRT_AUTH_TOKEN = "ZRT Auth token"

# Option B: SDK auto-generates token (omit ZRT_AUTH_TOKEN)
# ZRT_API_KEY = "Your Zero Runtime API Key"
# ZRT_SECRET_KEY = "Your Zero Runtime Secret Key"

.env

# Option A: pre-generated token
ZRT_AUTH_TOKEN="ZRT Auth token"

# Option B: SDK auto-generates token (omit ZRT_AUTH_TOKEN)
# ZRT_API_KEY="Your Zero Runtime API Key"
# ZRT_SECRET_KEY="Your Zero Runtime Secret Key"

# Used by GeminiRealtime
GOOGLE_API_KEY="Google Live API Key"

Get a Gemini key from Google AI Studio. For Zero Runtime, use an auth token from the Zero Runtime Dashboard or an API key + secret. Follow the guide.

Build the agent

The agent must register itself with Zero Runtime so calls can be routed to it. Give it a unique agent_id and start it with zrt.serve(), which registers it automatically. WhatsApp calls arrive through your routing rule, so there is no playground to open. Just keep the process running.

Cascade
Realtime

main.py

import logging

import zrt
from zrt import Agent, Pipeline
from zrt.plugins import SileroVAD, TurnDetector
from zrt.plugins import CartesiaSTT, GoogleLLM, CartesiaTTS
from zrt.inference import AICousticsDenoise
from dotenv import load_dotenv

logging.basicConfig(level=logging.INFO)
load_dotenv()

AGENT_ID = "agent1"  # unique ID used for call routing

pipeline = Pipeline(
    stt=CartesiaSTT(model="ink-2"),
    llm=GoogleLLM(model="gemini-2.5-flash"),
    tts=CartesiaTTS(model="sonic-2"),
    vad=SileroVAD(threshold=0.35),
    turn_detector=TurnDetector(model="echo-large"),
    denoise=AICousticsDenoise(model_id="quail-vf-2.2-l-16khz"),
)


class WhatsappAgent(Agent):
    def __init__(self):
        super().__init__(
            agent_id=AGENT_ID,
            instructions="You are a friendly assistant answering WhatsApp calls. Keep responses concise.",
            pipeline=pipeline,
        )

    async def on_enter(self):
        await self.session.say("Hello! You've reached the Zero Runtime assistant. How can I help you today?")

    async def on_exit(self):
        await self.session.say("Thank you for calling. Goodbye!")


def on_ready():
    logging.info("Agent registered as %s and ready for calls.", AGENT_ID)


if __name__ == "__main__":
    # Pass the class itself (not an instance): serve() builds a fresh WhatsappAgent +
    # pipeline per call, which is required for correct per-call state under concurrent calls.
    zrt.serve(WhatsappAgent, on_ready=on_ready)

main.py

import os, logging

import zrt
from zrt import Agent, Pipeline
from zrt.plugins import GeminiRealtime, GeminiLiveConfig
from dotenv import load_dotenv

logging.basicConfig(level=logging.INFO)
load_dotenv()

AGENT_ID = "agent1"  # unique ID used for call routing

model = GeminiRealtime(
    api_key=os.getenv("GOOGLE_API_KEY"),
    config=GeminiLiveConfig(
        model="gemini-3.1-flash-live-preview",
        voice="Leda",
        response_modalities=["AUDIO"],
    ),
)
pipeline = Pipeline(llm=model)


class WhatsappAgent(Agent):
    def __init__(self):
        super().__init__(
            agent_id=AGENT_ID,
            instructions="You are a friendly assistant answering WhatsApp calls. Keep responses concise.",
            pipeline=pipeline,
        )

    async def on_enter(self):
        await self.session.say("Hello! You've reached the Zero Runtime assistant. How can I help you today?")

    async def on_exit(self):
        await self.session.say("Thank you for calling. Goodbye!")


def on_ready():
    logging.info("Agent registered as %s and ready for calls.", AGENT_ID)


if __name__ == "__main__":
    # Pass the class itself (not an instance): serve() builds a fresh WhatsappAgent +
    # pipeline per call, which is required for correct per-call state under concurrent calls.
    zrt.serve(WhatsappAgent, on_ready=on_ready)

Declare your dependencies in a pyproject.toml, then let uv build the environment and run the agent:

Cascade
Realtime

pyproject.toml

[project]
name = "zrt-whatsapp-agent"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
  "zrt",
  "python-dotenv",
]

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

pyproject.toml

[project]
name = "zrt-whatsapp-agent"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
  "zrt",
  "python-dotenv",
]

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

uv sync                 # creates the .venv and installs the dependencies
uv run python main.py

Keep the process running. It registers with Zero Runtime using the ID agent1.

Agent running locally and registering with Zero Runtime

Configure Zero Runtime gateways

Set up two gateways so Zero Runtime can route WhatsApp calls in and out. Use the Dashboard or the API for each.1. Inbound gateway: the entry point for incoming WhatsApp calls.

Dashboard
API

In the Zero Runtime Dashboard, go to Telephony > Inbound Gateways and click Add.
Enter a gateway name (e.g. WhatsApp Gateway).
Add your WhatsApp Business phone number and click Create.

curl --request POST \
  --url https://api.videosdk.live/v2/sip/inbound-gateways \
  --header 'Authorization: YOUR_ZRT_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "WhatsApp Gateway", "numbers": ["+1234567890"] }'

2. Outbound gateway: lets the agent dial out to WhatsApp numbers. First fetch the SIP credentials from Meta:

curl --globoff 'https://graph.facebook.com/v17.0/{{phone_id}}/settings?include_sip_credentials=true' \
  --header 'Authorization: Bearer {{access_token}}'

Use the returned hostname (address) and sip_user_password (password) to create the gateway.

Dashboard
API

In the Zero Runtime Dashboard, go to Telephony > Outbound Gateways and click Add.
Enter a gateway name.
Provide the SIP details from Meta (the hostname as the address, your WhatsApp number as the username, and sip_user_password as the password), then click Create.

curl --request POST \
  --url https://api.videosdk.live/v2/sip/outbound-gateways \
  --header 'Authorization: YOUR_ZRT_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "WhatsApp Outbound",
    "numbers": ["+1234567890"],
    "address": "9WXXXXXXXX.sip.videosdk.live",
    "auth": { "username": "your_whatsapp_number", "password": "v18yo40Lhxxxxxx" }
  }'

Create a routing rule

Connect the inbound gateway to your agent by ID. The agent ID must match the agent_id you pass to your agent (registered by zrt.serve()).

Dashboard
API

In the Zero Runtime Dashboard, go to Telephony > Routing Rules and click Add.
Select your inbound gateway (e.g. WhatsApp Gateway).
Add your WhatsApp Business phone number.
Set Dispatch to Agent and Agent Type to Self Hosted.
Enter the Agent ID as agent1 (must match main.py) and click Create.

curl --request POST \
  --url https://api.videosdk.live/v2/sip/routing-rules \
  --header 'Authorization: YOUR_ZRT_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "gatewayId": "your_inbound_gateway_id",
    "name": "WhatsApp Call Routing",
    "numbers": ["+1234567890"],
    "dispatch": "agent",
    "agentType": "self_hosted",
    "agentId": "agent1"
  }'

Enable WhatsApp SIP forwarding

Tell Meta to forward incoming WhatsApp calls to your inbound gateway. Substitute the inbound gateway hostname (it appears in the dashboard).

curl --location 'https://graph.facebook.com/v19.0/{{phone_number_id}}/settings' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "calling": {
      "status": "ENABLED",
      "sip": {
        "status": "ENABLED",
        "servers": [ { "hostname": "9WXXXXXXX.sip.videosdk.live" } ]
      },
      "srtp_key_exchange_protocol": "DTLS"
    }
  }'

A successful response is { "success": true }.

Place a test call

Make sure your main.py script is still running locally before making or receiving calls. The agent must be active to handle any communication.

Inbound
Outbound

From a different WhatsApp account, place a voice call to your WhatsApp Business number. The agent answers and greets you.

Trigger a call from the agent through your outbound gateway. Replace gatewayId and sipCallTo.

curl --request POST \
  --url https://api.videosdk.live/v2/sip/call \
  --header 'Authorization: YOUR_ZRT_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "gatewayId": "your_outbound_gateway_id", "sipCallTo": "whatsapp_number_to_call" }'

For optimal performance, run your agent in the same geographic region as your SIP provider. This reduces latency and improves call quality.

Verify

The agent registers under the ID agent1 and the worker process stays running.
An incoming WhatsApp call reaches the agent and you hear the greeting.
Outbound calls dial the target WhatsApp number through your outbound gateway.

Common errors:

agent_id mismatch: the routing rule’s agentId must exactly match the agent’s agent_id.
Missing Meta permission: the access token needs whatsapp_business_management.
SIP forwarding off: the Meta calling.sip.status must be ENABLED.
Agent not running: the worker process must be alive to accept the inbound call.

Get started

SIP Connect

Managing Calls

Call Routing

Integrations

Build a WhatsApp Agent with Zero Runtime

Architecture

Prerequisites

Verify

What’s Next

Telephony docs

Deploy an agent

References

​Architecture

​Prerequisites

​Verify

​What’s Next

Telephony docs

Deploy an agent

​References

Architecture

Prerequisites

Verify

What’s Next

References