AI Agent Calls - Zeeg Developer Hub

Zeeg’s AI Agent can make outbound phone calls on your behalf. Use the API to trigger calls immediately or schedule them for a specific time. This guide walks you through both scenarios.

Prerequisites

Before you begin, make sure you have the following in place:

An AI agent created, published, and enabled in your Zeeg dashboard
The agent’s UUID (found in the agent settings)
An API token with the outbound-calls:write scope

Triggering an Immediate Call

Send a POST request to start a call right away. The AI agent will dial the specified phone number and use the provided context to drive the conversation. Endpoint

POST https://api.zeeg.me/v2/agents/{agentUuid}/outbound-calls

Required fields

Field	Type	Description
`phoneNumber`	string	Phone number in E.164 format (e.g., `+4915112345678`)
`email`	string	Contact’s email address
`fullName`	string	Contact’s full name

Optional fields

Field	Type	Description
`additionalData`	string	Extra context for the AI agent to use during the call
`scheduledTime`	string	Schedule the call for later (see Scheduling a Future Call)

Phone numbers must be in E.164 format — a + followed by the country code and subscriber number with no spaces or dashes. For example: +4915112345678 (Germany) or +14155551234 (US).

curl -X POST https://api.zeeg.me/v2/agents/YOUR_AGENT_UUID/outbound-calls \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "phoneNumber": "+4915112345678",
    "email": "alex.mueller@example.com",
    "fullName": "Alex Mueller",
    "additionalData": "Follow up on demo request from March 28. Interested in the Enterprise plan."
  }'

import requests

response = requests.post(
    "https://api.zeeg.me/v2/agents/YOUR_AGENT_UUID/outbound-calls",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={
        "phoneNumber": "+4915112345678",
        "email": "alex.mueller@example.com",
        "fullName": "Alex Mueller",
        "additionalData": "Follow up on demo request from March 28. Interested in the Enterprise plan.",
    },
)
print(response.json())

const response = await fetch(
  "https://api.zeeg.me/v2/agents/YOUR_AGENT_UUID/outbound-calls",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_TOKEN",
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify({
      phoneNumber: "+4915112345678",
      email: "alex.mueller@example.com",
      fullName: "Alex Mueller",
      additionalData:
        "Follow up on demo request from March 28. Interested in the Enterprise plan.",
    }),
  }
);
const data = await response.json();
console.log(data);

Use additionalData to give your AI agent relevant context about the person being called — prior interactions, the reason for the call, or specific talking points. This makes conversations more personalized and effective.

Scheduling a Future Call

To schedule a call for a later time, include the scheduledTime field in the same request. The value must be a future datetime in YYYY-MM-DD HH:mm:ss format.

curl -X POST https://api.zeeg.me/v2/agents/YOUR_AGENT_UUID/outbound-calls \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "phoneNumber": "+4915112345678",
    "email": "alex.mueller@example.com",
    "fullName": "Alex Mueller",
    "scheduledTime": "2026-04-10 14:30:00",
    "additionalData": "Quarterly check-in call. Discuss renewal options."
  }'

import requests

response = requests.post(
    "https://api.zeeg.me/v2/agents/YOUR_AGENT_UUID/outbound-calls",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={
        "phoneNumber": "+4915112345678",
        "email": "alex.mueller@example.com",
        "fullName": "Alex Mueller",
        "scheduledTime": "2026-04-10 14:30:00",
        "additionalData": "Quarterly check-in call. Discuss renewal options.",
    },
)
print(response.json())

const response = await fetch(
  "https://api.zeeg.me/v2/agents/YOUR_AGENT_UUID/outbound-calls",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_TOKEN",
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify({
      phoneNumber: "+4915112345678",
      email: "alex.mueller@example.com",
      fullName: "Alex Mueller",
      scheduledTime: "2026-04-10 14:30:00",
      additionalData:
        "Quarterly check-in call. Discuss renewal options.",
    }),
  }
);
const data = await response.json();
console.log(data);

Response

A successful request returns the created call object with a 201 status code.

{
  "id": 42,
  "status": "pending",
  "agentId": "YOUR_AGENT_UUID",
  "phoneNumber": "+4915112345678",
  "email": "alex.mueller@example.com",
  "fullName": "Alex Mueller",
  "additionalData": "Follow up on demo request from March 28. Interested in the Enterprise plan.",
  "scheduledTime": null
}

Status values

Status	Description
`pending`	Call is queued or scheduled
`completed`	Call finished successfully
`failed`	Call could not be completed

Error Handling

Status	Error	Description
`400`	Agent is not active	The agent must be published and enabled in the dashboard
`403`	Missing scope	Your API token does not have the `outbound-calls:write` scope
`404`	Agent not found	No agent exists with the provided UUID
`422`	Invalid phone number format	The phone number is not in valid E.164 format
`422`	Scheduled time in the past	`scheduledTime` must be a future datetime

Integration Example

You can combine this API with workflow automation tools to trigger calls based on external events. For a step-by-step walkthrough using n8n, see the guide:

Build a Workflow with n8n and Zeeg

Automate outbound calls by connecting Zeeg’s AI Agent API to n8n workflows.

​Prerequisites

​Triggering an Immediate Call

​Scheduling a Future Call

​Response

​Error Handling

​Integration Example

Build a Workflow with n8n and Zeeg

Prerequisites

Triggering an Immediate Call

Scheduling a Future Call

Response

Error Handling

Integration Example