### Install Zavu SDKs

Source: https://docs.zavu.dev/quickstart

Install the Zavu SDK for your language to begin sending messages. Available for Node.js (npm/bun) and Python (pip/uv).

```bash
npm add @zavudev/sdk
# or: bun add @zavudev/sdk
```

```bash
pip install zavudev
# or: uv add zavudev
```

--------------------------------

### System Prompt Example for AI Agent

Source: https://docs.zavu.dev/guides/ai-agents/setup

Example of a system prompt to define an AI agent's behavior and personality. This prompt includes guidelines for a customer support agent, specifying tone, response length, and handling of unknown information or specific issues.

```text
You are a helpful customer support agent for [Company Name].

Guidelines:
- Be friendly and professional
- Keep responses concise (under 160 characters for SMS)
- If you don't know the answer, say so
- For billing issues, direct customers to billing@company.com
- Never share sensitive information
```

--------------------------------

### API Key Environment Variable Example

Source: https://docs.zavu.dev/quickstart

Store your Zavu API key securely in your environment variables. This is a common practice to avoid hardcoding sensitive credentials directly in your code.

```bash
export ZAVU_API_KEY="zv_live_your_api_key_here"
```

--------------------------------

### Create AI Agent via API - TypeScript, Python, cURL

Source: https://docs.zavu.dev/guides/ai-agents/setup

Code examples for creating an AI agent programmatically using the Zavu Dev SDK and API. Demonstrates configuration of agent settings like provider, model, system prompt, and trigger channels.

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({
  apiKey: process.env["ZAVUDEV_API_KEY"],
});

const agent = await zavu.senders.agent.create("sender_abc123", {
  enabled: true,
  provider: "openai",
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY, // Not needed for Zavu provider
  systemPrompt: `You are a helpful customer support agent for Acme Corp.
Be friendly and concise. If you don't know the answer, say so.`,
  temperature: 0.7,
  maxTokens: 500,
  contextWindowMessages: 10,
  triggerOnChannels: ["sms", "whatsapp"],
});

console.log("Agent ID:", agent.id);
```

```python
import os
from zavudev import Zavudev

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),
)

agent = zavu.senders.agent.create(
    "sender_abc123",
    enabled=True,
    provider="openai",
    model="gpt-4o-mini",
    api_key=os.environ.get("OPENAI_API_KEY"),  # Not needed for Zavu provider
    system_prompt="""You are a helpful customer support agent for Acme Corp.
Be friendly and concise. If you don't know the answer, say so.""",
    temperature=0.7,
    max_tokens=500,
    context_window_messages=10,
    trigger_on_channels=["sms", "whatsapp"],
)

print(f"Agent ID: {agent.id}")
```

```bash
curl -X POST https://api.zavu.dev/v1/senders/sender_abc123/agent \
  -H "Authorization: Bearer $ZAVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "enabled": true,
      "provider": "openai",
      "model": "gpt-4o-mini",
      "apiKey": "sk-...",
      "systemPrompt": "You are a helpful customer support agent for Acme Corp.\nBe friendly and concise.",
      "temperature": 0.7,
      "maxTokens": 500,
      "contextWindowMessages": 10,
      "triggerOnChannels": ["sms", "whatsapp"]
    }'
```

--------------------------------

### Send First Message with Zavu SDKs

Source: https://docs.zavu.dev/quickstart

Send your first message using the Zavu SDK. This example demonstrates sending a simple text message to a specified phone number. Ensure your ZAVU_API_KEY is set in your environment variables.

```typescript
import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev({
  apiKey: process.env['ZAVUDEV_API_KEY'], // This is the default and can be omitted
});

const result = await zavu.messages.send({
  to: "+14155551234",
  text: "Hello from Zavu!",
});

console.log("Message ID:", result.message.id);
console.log("Status:", result.message.status);
```

```python
import os
from zavudev import Zavudev

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),  # This is the default and can be omitted
)

result = zavu.messages.send(
    to="+14155551234",
    text="Hello from Zavu!",
)

print(f"Message ID: {result.message.id}")
print(f"Status: {result.message.status}")
```

--------------------------------

### Install Zavu SDK

Source: https://docs.zavu.dev/sdks/typescript/overview

Installs the Zavu SDK using npm, bun, or yarn. Ensure you have Node.js 18+ installed.

```bash
npm add @zavudev/sdk
# or
bun add @zavudev/sdk
# or
yarn add @zavudev/sdk
```

--------------------------------

### Send First Message with cURL

Source: https://docs.zavu.dev/quickstart

Send your first message using a cURL request to the Zavu API. This example shows how to make a POST request with the necessary headers and JSON payload. Replace `$ZAVUDEV_API_KEY` with your actual API key.

```bash
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "text": "Hello from Zavu!"
  }'
```

--------------------------------

### Full Invitation Workflow Example (Python)

Source: https://docs.zavu.dev/sdks/python/invitations

A comprehensive example demonstrating the creation of an invitation and checking its status. Includes helper functions for onboarding clients and verifying invitation progress.

```python
import os
from zavu import Zavu

client = Zavu(api_key=os.environ["ZAVU_API_KEY"])

def onboard_client(client_name: str, client_email: str):
    """Create an invitation for a new client."""
    invitation = client.invitations.create(
        client_name=client_name,
        client_email=client_email,
        expires_in_days=7
    )

    print(f"Send this link to {client_name}: {invitation.url}")
    return invitation

def check_invitation_status(invitation_id: str):
    """Check the status of an invitation."""
    result = client.invitations.get(invitation_id=invitation_id)
    invitation = result.invitation

    match invitation.status:
        case "pending":
            print("Waiting for client to start signup")
        case "in_progress":
            print("Client is completing the signup flow")
        case "completed":
            print(f"Success! Sender ID: {invitation.sender_id}")
        case "expired":
            print("Invitation expired, create a new one")
        case "cancelled":
            print("Invitation was cancelled")

    return invitation

# Usage
invitation = onboard_client("Acme Corp", "contact@acme.com")
# Later...
check_invitation_status(invitation.id)
```

--------------------------------

### Install Zavu SDK

Source: https://docs.zavu.dev/guides/integrations/vercel

Install the Zavu SDK for Node.js (npm/bun) or Python (pip/uv). This is the first step to programmatically interact with Zavu services.

```bash
npm install @zavudev/sdk
# or: bun add @zavudev/sdk
```

```bash
pip install zavudev
# or: uv add zavudev
```

--------------------------------

### Complete Campaign Sending Example (TypeScript)

Source: https://docs.zavu.dev/guides/url-verification/overview

A comprehensive example showing how to pre-verify campaign URLs, handle potential verification errors, and then send messages with the verified URLs using the Zavudev SDK.

```typescript
import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev();

async function sendCampaignWithLinks() {
  const campaignUrls = [
    "https://mystore.example.com/sale",
    "https://mystore.example.com/new-arrivals",
  ];

  // 1. Pre-verify all campaign URLs
  console.log("Verifying campaign URLs...");

  for (const url of campaignUrls) {
    try {
      const result = await zavu.urls.submit({ url });
      console.log(`${url}: ${result.url.status}`);

      if (result.url.status !== "approved") {
        throw new Error(`URL not approved: ${url}`);
      }
    } catch (error) {
      console.error(`Failed to verify ${url}:`, error);
      return;
    }
  }

  // 2. Send messages with verified URLs
  console.log("\nSending campaign...");

  const message = await zavu.messages.send({
    to: "+14155551234",
    text: `Sale alert! Shop now: ${campaignUrls[0]}`,
  });

  console.log(`Message sent: ${message.id} (${message.status})`);
}

sendCampaignWithLinks();
```

--------------------------------

### Install Zavu SDK for Python

Source: https://docs.zavu.dev/sdks/python/overview

Installs the Zavu SDK using pip, uv, or poetry. Requires Python 3.9 or higher.

```bash
pip install zavudev
# or
uv add zavudev
# or
poetry add zavudev
```

--------------------------------

### Get Agent Configuration

Source: https://docs.zavu.dev/guides/ai-agents/setup

Retrieve the current configuration and status of a specific agent.

```APIDOC
## GET /v1/senders/{sender_id}/agent

### Description
Retrieves the current configuration and status of a specific agent, including its provider, model, enabled status, and statistics.

### Method
GET

### Endpoint
`/v1/senders/{sender_id}/agent`

### Parameters
#### Path Parameters
- **sender_id** (string) - Required - The unique identifier for the sender.

### Response
#### Success Response (200)
- **provider** (string) - LLM provider.
- **model** (string) - Model ID.
- **enabled** (boolean) - Agent status.
- **stats** (object) - Agent statistics.

#### Response Example
```json
{
  "provider": "openai",
  "model": "gpt-4o",
  "enabled": true,
  "stats": {
    "messages_sent": 150,
    "tokens_consumed": 12000
  }
}
```
```

--------------------------------

### Quick Start: Send a Message with Zavu SDK

Source: https://docs.zavu.dev/sdks/typescript/overview

Demonstrates how to initialize the Zavu client and send a message using the SDK. Requires an API key stored in environment variables.

```typescript
import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev({
  apiKey: process.env['ZAVUDEV_API_KEY'],
});

const result = await zavu.messages.send({
  to: "+14155551234",
  text: "Hello from Zavu!",
});

console.log("Message sent:", result.message.id);
```

--------------------------------

### Complete Customer Onboarding Example (TypeScript)

Source: https://docs.zavu.dev/guides/contacts/overview

Demonstrates a full customer onboarding workflow using the Zavu SDK. It includes validating a phone number via introspection, sending a welcome message, and updating the contact with provided customer data. This example highlights smart routing and metadata management.

```typescript
import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev();

async function processNewCustomer(phone: string, customerData: {
  name: string;
  email: string;
  plan: string;
}) {
  // 1. Validate the phone number
  const introspection = await zavu.introspect.phone({ phoneNumber: phone });

  if (!introspection.validNumber) {
    throw new Error("Invalid phone number");
  }

  console.log(`Valid ${introspection.lineType} number from ${introspection.countryCode}`);

  // 2. Send welcome message (creates contact automatically)
  const message = await zavu.messages.send({
    to: phone,
    channel: "auto", // Smart routing based on available channels
    text: `Welcome ${customerData.name}! Your ${customerData.plan} account is ready.`,
  });

  console.log(`Welcome message sent: ${message.id}`);

  // 3. Update contact with customer data
  const contact = await zavu.contacts.getByPhone(phone);

  await zavu.contacts.update(contact.id, {
    defaultChannel: introspection.availableChannels.includes("whatsapp")
      ? "whatsapp"
      : "sms",
    metadata: {
      name: customerData.name,
      email: customerData.email,
      plan: customerData.plan,
      signupDate: new Date().toISOString(),
    },
  });

  console.log(`Contact updated: ${contact.id}`);

  return contact;
}

// Usage
processNewCustomer("+14155551234", {
  name: "John Doe",
  email: "john@example.com",
  plan: "premium",
});
```

--------------------------------

### Send Telegram Message (Python)

Source: https://docs.zavu.dev/guides/telegram/setup

Example of sending a message to a Telegram chat using the Zavu SDK in Python. Requires the chat ID of the recipient and the Zavu SDK initialized.

```python
result = zavu.messages.send(
    to="123456789",  # Chat ID from inbound message
    text="Thanks for reaching out!",
    channel="telegram"
)
```

--------------------------------

### Send Telegram Message (TypeScript)

Source: https://docs.zavu.dev/guides/telegram/setup

Example of sending a message to a Telegram chat using the Zavu SDK in TypeScript. Requires the chat ID of the recipient and the Zavu SDK initialized.

```typescript
const result = await zavu.messages.send({
  to: "123456789", // Chat ID from inbound message
  text: "Thanks for reaching out!",
  channel: "telegram",
});
```

--------------------------------

### Initialize Zavu Client

Source: https://docs.zavu.dev/sdks/typescript/overview

Shows how to initialize the Zavu client with basic configuration using an API key or with a custom base URL.

```typescript
import Zavudev from '@zavudev/sdk';

// Basic initialization
const zavu = new Zavudev({
  apiKey: process.env['ZAVUDEV_API_KEY'],
});

// With custom base URL
const zavu = new Zavudev({
  apiKey: "zv_live_xxx",
  baseURL: "https://api.zavu.dev",
});
```

--------------------------------

### Example API Response for Sending Message

Source: https://docs.zavu.dev/quickstart

This JSON object represents a successful response from the Zavu API after sending a message. It includes details about the message ID, recipient, sender, channel, status, and creation timestamp.

```json
{
  "message": {
    "id": "jd70x0ms07pbfyknb2hj8akznn7whac3",
    "to": "+14155551234",
    "from": "+14155559876",
    "channel": "sms",
    "status": "queued",
    "messageType": "text",
    "text": "Hello from Zavu!",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}
```

--------------------------------

### Full Zavu Invitation Management Example with TypeScript SDK

Source: https://docs.zavu.dev/sdks/typescript/invitations

A comprehensive example demonstrating the workflow of onboarding a client using the Zavu TypeScript SDK. It includes creating an invitation, logging the invitation URL, and later checking the invitation status, providing feedback based on the current state.

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({
  apiKey: process.env["ZAVUDEV_API_KEY"],
});

async function onboardClient(clientName: string, clientEmail: string) {
  // Create invitation
  const invitation = await zavu.invitations.create({
    clientName,
    clientEmail,
    expiresInDays: 7,
  });

  console.log(`Send this link to ${clientName}: ${invitation.url}`);

  return invitation;
}

async function checkInvitationStatus(invitationId: string) {
  const { invitation } = await zavu.invitations.get({ invitationId });

  switch (invitation.status) {
    case "pending":
      console.log("Waiting for client to start signup");
      break;
    case "in_progress":
      console.log("Client is completing the signup flow");
      break;
    case "completed":
      console.log(`Success! Sender ID: ${invitation.senderId}`);
      break;
    case "expired":
      console.log("Invitation expired, create a new one");
      break;
    case "cancelled":
      console.log("Invitation was cancelled");
      break;
  }

  return invitation;
}

// Usage
const invitation = await onboardClient("Acme Corp", "contact@acme.com");
// Later...
await checkInvitationStatus(invitation.id);
```

--------------------------------

### Appointment Booking Flow Example

Source: https://docs.zavu.dev/guides/ai-agents/flows

An example JSON structure for an 'Appointment Booking' conversational flow. This flow guides users through selecting a service, date, and time, and then uses tools to check availability and book the appointment. It includes date validation and options for service types.

```json
{
  "name": "Book Appointment",
  "trigger": {
    "type": "keyword",
    "keywords": ["book", "appointment", "schedule", "meeting"]
  },
  "steps": [
    {
      "id": "welcome",
      "type": "message",
      "content": "I'd be happy to help you book an appointment!"
    },
    {
      "id": "service",
      "type": "collect",
      "variable": "service_type",
      "prompt": "What type of appointment?",
      "validation": {
        "type": "options",
        "options": ["Consultation", "Follow-up", "New Patient"]
      }
    },
    {
      "id": "date",
      "type": "collect",
      "variable": "preferred_date",
      "prompt": "What date works best? (e.g., Monday, Dec 20)",
      "validation": { "type": "date" }
    },
    {
      "id": "check_slots",
      "type": "tool",
      "toolName": "get_available_slots",
      "parameters": {
        "date": "{{preferred_date}}",
        "service": "{{service_type}}"
      },
      "resultVariable": "slots"
    },
    {
      "id": "show_slots",
      "type": "message",
      "content": "Available times on {{preferred_date}}: {{slots}}"
    },
    {
      "id": "time",
      "type": "collect",
      "variable": "selected_time",
      "prompt": "Which time works for you?"
    },
    {
      "id": "book",
      "type": "tool",
      "toolName": "create_appointment",
      "parameters": {
        "date": "{{preferred_date}}",
        "time": "{{selected_time}}",
        "service": "{{service_type}}"
      }
    },
    {
      "id": "confirm",
      "type": "message",
      "content": "Your {{service_type}} appointment is booked for {{preferred_date}} at {{selected_time}}. See you then!"
    }
  ]
}
```

--------------------------------

### SaaS Onboarding Flow

Source: https://docs.zavu.dev/guides/partner-invitations/api

Integrate WhatsApp setup into your SaaS onboarding by creating Zavu invitations and sending them to customers.

```APIDOC
## POST /invitations

### Description
Creates a new Zavu invitation for a client to set up their WhatsApp Business.

### Method
POST

### Endpoint
/invitations

### Parameters
#### Request Body
- **clientName** (string) - Required - The name of the client's company.
- **clientEmail** (string) - Required - The email address of the client.
- **expiresInDays** (integer) - Optional - The number of days until the invitation expires. Defaults to 14.

### Request Example
```json
{
  "clientName": "Acme Corp",
  "clientEmail": "contact@acme.com",
  "expiresInDays": 14
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the invitation.
- **url** (string) - The URL for the client to complete the onboarding.
- **status** (string) - The current status of the invitation (e.g., 'pending', 'completed').

#### Response Example
```json
{
  "id": "inv_abc123",
  "url": "https://zavu.app/onboard?token=xyz789",
  "status": "pending"
}
```
```

--------------------------------

### WhatsApp Channel Setup

Source: https://docs.zavu.dev/guides/senders/adding-channels

Guides users through the process of connecting a WhatsApp number to their Zavu sender, offering options for Zavu-provided numbers or personal numbers.

```APIDOC
## WhatsApp Channel Setup

### Description
Connect your WhatsApp number to your Zavu sender. You can choose between using a dedicated Zavu phone number or registering your own number via SMS/call verification.

### Connection Options

*   **Zavu Phone Number:** Recommended for dedicated business lines. Verification is done via a voice call.
*   **Own Phone Number:** Register any phone number you own through SMS or call verification.

### Setup Steps

1.  **Open WhatsApp Setup:** Navigate to the **Channels** tab of your sender and click **Add** next to WhatsApp.
2.  **Choose Connection Method:** Select either a Zavu phone number or your own.
3.  **Complete Meta Business Signup:** Follow the Meta embedded signup wizard.
4.  **Verify Phone Number:** Enter your phone number and select **Call** verification for Zavu numbers.
5.  **Enter Verification Code:** Input the code received to finalize setup.

### Post-Connection Information

Upon successful connection, sender responses will include WhatsApp details:

```json
{
  "id": "sender_12345",
  "name": "Support",
  "phoneNumber": "+15551234567",
  "whatsapp": {
    "phoneNumberId": "123456789012345",
    "displayPhoneNumber": "+15551234567",
    "paymentStatus": {
      "setupStatus": "COMPLETE",
      "methodStatus": "VALID",
      "canSendTemplates": true
    }
  }
}
```

### Next Steps

*   Configure your [WhatsApp Business Profile](/guides/whatsapp/profile).
*   Create [message templates](/guides/whatsapp/templates/overview) for outbound conversations.
```

--------------------------------

### Initialize Zavu Client

Source: https://docs.zavu.dev/sdks/python/overview

Initializes the Zavu client with an API key, optionally specifying a custom base URL.

```python
from zavudev import Zavudev

# Basic initialization
zavu = Zavudev(
    api_key="zv_live_xxx",
)

# With custom base URL
zavu = Zavudev(
    api_key="zv_live_xxx",
    base_url="https://api.zavu.dev"
)
```

--------------------------------

### Uploading Documents

Source: https://docs.zavu.dev/guides/phone-numbers/regulatory-requirements

This section provides a comprehensive guide on how to upload documents, including prerequisites, steps, and code examples in TypeScript, Python, and cURL.

```APIDOC
## Uploading Documents

### Description
This endpoint allows you to upload documents required for verification. The process involves obtaining an upload URL, uploading the file to storage, and then creating a document record with the storage identifier.

### Method
POST

### Endpoint
`/v1/documents`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name of the document (e.g., "John Doe Passport")
- **documentType** (string) - Required - The type of document (e.g., "passport", "national_id")
- **storageId** (string) - Required - The identifier returned after uploading the file to storage
- **mimeType** (string) - Required - The MIME type of the file (e.g., "image/jpeg")
- **fileSize** (integer) - Required - The size of the file in bytes

### Request Example (cURL)
```bash
# Step 1: Get upload URL (This is a conceptual step, actual URL obtained from a separate call)
# curl -X POST https://api.zavu.dev/v1/documents/upload-url -H "Authorization: Bearer $ZAVU_API_KEY"

# Assuming uploadUrl returns a URL and storageId is obtained after uploading the file
STORAGE_ID="your_storage_id_here"

curl -X POST https://api.zavu.dev/v1/documents \
  -H "Authorization: Bearer $ZAVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"John Doe Passport\",
    \"documentType\": \"passport\",
    \"storageId\": \"$STORAGE_ID\",
    \"mimeType\": \"image/jpeg\",
    \"fileSize\": 102400
  }"
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the created document record.
- **status** (string) - The current status of the document (e.g., "pending", "verified", "rejected").

#### Response Example
```json
{
  "id": "doc_123abc456",
  "status": "pending"
}
```

### Supported Document Types
- **passport**: Government-issued passport
- **national_id**: National identity card
- **drivers_license**: Driver's license
- **utility_bill**: Utility bill (for proof of address)
- **tax_id**: Tax identification document
- **business_registration**: Business registration certificate
- **proof_of_address**: Bank statement or official letter
- **other**: Other document type

### File Requirements
- **Formats**: JPEG, PNG, or PDF
- **Max size**: 10MB
- **Quality**: Clear, readable scan or photo
- **Validity**: Document must not be expired
```

--------------------------------

### Onboard New Customer with WhatsApp Invitation (TypeScript)

Source: https://docs.zavu.dev/guides/partner-invitations/api

This function handles the onboarding of a new customer by creating a Zavu invitation for WhatsApp setup, sending an email with the invitation link, and storing the invitation ID for tracking. It assumes the existence of `Customer` type, `createCustomer`, `zavu.invitations.create`, `sendEmail`, and `saveInvitationId` functions.

```typescript
async function onboardNewCustomer(customer: Customer) {
  // 1. Create the customer in your system
  await createCustomer(customer);

  // 2. Create a Zavu invitation
  const invitation = await zavu.invitations.create({
    clientName: customer.companyName,
    clientEmail: customer.email,
    expiresInDays: 14,
  });

  // 3. Send onboarding email with the invitation link
  await sendEmail({
    to: customer.email,
    subject: 'Connect Your WhatsApp Business',
    body: `
      Welcome to our platform!

      To enable WhatsApp messaging, please complete the setup:
      ${invitation.url}

      This link expires in 14 days.
    `,
  });

  // 4. Store the invitation ID for tracking
  await saveInvitationId(customer.id, invitation.id);
}
```

--------------------------------

### Run MCP Server via npx

Source: https://docs.zavu.dev/tools/mcp-server

Quick start guide to run the MCP Server directly using npx. Requires setting the ZAVUDEV_API_KEY environment variable.

```bash
export ZAVUDEV_API_KEY="Your API Key"
npx -y @zavudev/sdk-mcp@latest
```

--------------------------------

### Update Agent Configuration

Source: https://docs.zavu.dev/guides/ai-agents/setup

Update an existing agent's system prompt, temperature, model, or other configuration settings. This endpoint allows for fine-tuning agent behavior and capabilities.

```APIDOC
## PATCH /v1/senders/{sender_id}/agent

### Description
Updates the configuration of a specific agent, allowing modification of parameters such as `systemPrompt`, `temperature`, `model`, and `enabled` status.

### Method
PATCH

### Endpoint
`/v1/senders/{sender_id}/agent`

### Parameters
#### Path Parameters
- **sender_id** (string) - Required - The unique identifier for the sender.

#### Request Body
- **systemPrompt** (string) - Optional - Instructions that define the agent's behavior.
- **temperature** (number) - Optional - Response creativity (0 = deterministic, 2 = creative).
- **model** (string) - Optional - Model ID (e.g., `gpt-4o-mini`, `claude-3-5-haiku`).
- **enabled** (boolean) - Optional - Whether the agent responds to messages.
- **provider** (string) - Optional - LLM provider: `openai`, `anthropic`, `google`, `mistral`, `zavu`.
- **apiKey** (string) - Optional - Provider API key (not needed for `zavu` provider).
- **maxTokens** (number) - Optional - Maximum tokens in the response.
- **contextWindowMessages** (number) - Optional - Number of previous messages to include as context.
- **triggerOnChannels** (array) - Optional - Channels that activate the agent: `["sms", "whatsapp"]`.

### Request Example
```json
{
  "systemPrompt": "Updated system prompt...",
  "temperature": 0.5,
  "model": "gpt-4o",
  "enabled": true
}
```

### Response
#### Success Response (200)
- **provider** (string) - LLM provider.
- **model** (string) - Model ID.
- **enabled** (boolean) - Agent status.
- **stats** (object) - Agent statistics.

#### Response Example
```json
{
  "provider": "openai",
  "model": "gpt-4o",
  "enabled": true,
  "stats": {
    "messages_sent": 150,
    "tokens_consumed": 12000
  }
}
```
```

--------------------------------

### Initialize Zavu SDK with API Key (Python)

Source: https://docs.zavu.dev/authentication

Illustrates initializing the Zavu SDK in Python with an API key. It's recommended to retrieve the API key from environment variables.

```python
import os
from zavudev import Zavudev

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),  # This is the default and can be omitted
)
```

--------------------------------

### Zavu Broadcast Response with Reservation Details (JSON)

Source: https://docs.zavu.dev/guides/broadcasts/sending

Example JSON response when a broadcast starts, including details about the reservation made for estimated costs. This response helps in understanding the financial commitment for a broadcast.

```json
{
  "id": "brd_abc123",
  "status": "sending",
  "totalContacts": 1500,
  "estimatedCost": 25.00,
  "reservedAmount": 25.00,
  "startedAt": "2024-01-15T10:30:00.000Z"
}
```

--------------------------------

### Get Contact by Phone Number (TypeScript, Python, cURL)

Source: https://docs.zavu.dev/guides/contacts/overview

Illustrates how to find a contact record using their phone number. Includes examples in TypeScript, Python, and cURL, demonstrating how to check for contact existence and retrieve their associated data.

```typescript
const contact = await zavu.contacts.getByPhone("+14155551234");

if (contact) {
  console.log(`Found contact: ${contact.id}`);
  console.log(`Available channels: ${contact.availableChannels}`);
} else {
  console.log("Contact not found");
}
```

```python
contact = zavu.contacts.get_by_phone("+14155551234")

if contact:
    print(f"Found contact: {contact.id}")
    print(f"Available channels: {contact.available_channels}")
else:
    print("Contact not found")
```

```bash
# URL-encode the phone number (+14155551234 becomes %2B14155551234)
curl https://api.zavu.dev/v1/contacts/phone/%2B14155551234 \
  -H "Authorization: Bearer $ZAVU_API_KEY"
```

--------------------------------

### Quick Start: Send a Message with Zavu SDK

Source: https://docs.zavu.dev/sdks/python/overview

Sends a message using the Zavu SDK. Requires an API key set as an environment variable.

```python
import os
from zavudev import Zavudev

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),
)

result = zavu.messages.send(
    to="+14155551234",
    text="Hello from Zavu!"
)

print(f"Message sent: {result.message.id}")
```

--------------------------------

### Enable/Disable Agent (TypeScript, Python, cURL)

Source: https://docs.zavu.dev/guides/ai-agents/setup

Control the active state of an agent. You can disable an agent to stop it from responding or re-enable it to resume operations. This requires the agent's ID and a boolean value for the 'enabled' field.

```typescript
// Disable agent
await zavu.senders.agent.update("sender_abc123", {
    enabled: false,
  });

// Re-enable agent
await zavu.senders.agent.update("sender_abc123", {
    enabled: true,
  });
```

```python
# Disable agent
zavu.senders.agent.update("sender_abc123", enabled=False)

# Re-enable agent
zavu.senders.agent.update("sender_abc123", enabled=True)
```

```bash
# Disable agent
curl -X PATCH https://api.zavu.dev/v1/senders/sender_abc123/agent \
    -H "Authorization: Bearer $ZAVU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"enabled": false}'
```

--------------------------------

### Get Contact by ID (TypeScript, Python, cURL)

Source: https://docs.zavu.dev/guides/contacts/overview

Provides examples for retrieving a contact's details using their unique identifier. Supports TypeScript, Python, and cURL, showcasing how to access properties like phone number, country code, and available channels.

```typescript
import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev();

const contact = await zavu.contacts.get("con_abc123");

console.log(`Phone: ${contact.phoneNumber}`);
console.log(`Country: ${contact.countryCode}`);
console.log(`Channels: ${contact.availableChannels.join(", ")}`);
console.log(`Profile: ${contact.profileName || "Unknown"}`);
```

```python
from zavudev import Zavudev

zavu = Zavudev()

contact = zavu.contacts.get("con_abc123")

print(f"Phone: {contact.phone_number}")
print(f"Country: {contact.country_code}")
print(f"Channels: {', '.join(contact.available_channels)}")
print(f"Profile: {contact.profile_name or 'Unknown'}")
```

```bash
curl https://api.zavu.dev/v1/contacts/{contactId} \
  -H "Authorization: Bearer $ZAVU_API_KEY"
```

--------------------------------

### Async Usage Example

Source: https://docs.zavu.dev/sdks/python/broadcasts

Demonstrates how to use the Broadcasts API asynchronously with Python's asyncio library.

```APIDOC
## Async Usage Example

### Description
Provides an example of how to interact with the Broadcasts API using asynchronous Python code.

### Language
Python

### Code Example
```python
import asyncio
from zavudev import AsyncZavudev

async def main():
    client = AsyncZavudev()

    result = await client.broadcasts.create(
        name="Async Campaign",
        channel="sms",
        text="Hello {{name}}!"
    )
    print(result.broadcast.id)

asyncio.run(main())
```
```

--------------------------------

### Retrieve Agent Configuration (TypeScript, Python, cURL)

Source: https://docs.zavu.dev/guides/ai-agents/setup

Fetch the current configuration of a specific agent using its ID. The retrieved data includes details such as the provider, model, enabled status, and statistics. This is useful for auditing or displaying agent settings.

```typescript
const agent = await zavu.senders.agent.retrieve("sender_abc123");

console.log("Provider:", agent.provider);
console.log("Model:", agent.model);
console.log("Enabled:", agent.enabled);
console.log("Stats:", agent.stats);
```

```python
agent = zavu.senders.agent.retrieve("sender_abc123")

print(f"Provider: {agent.provider}")
print(f"Model: {agent.model}")
print(f"Enabled: {agent.enabled}")
print(f"Stats: {agent.stats}")
```

```bash
curl https://api.zavu.dev/v1/senders/sender_abc123/agent \
    -H "Authorization: Bearer $ZAVU_API_KEY"
```

--------------------------------

### Configure MCP Client and Capabilities

Source: https://docs.zavu.dev/tools/mcp-server

Examples of configuring the MCP client type and advanced capabilities for optimized compatibility and functionality.

```bash
# Specify MCP client
--client=claude
--client=claude-code
--client=cursor
--client=openai-agents

# Advanced configuration using capabilities
--capability=top-level-unions
--capability=tool-name-length=40
--capability=refs
--capability=unions
```

--------------------------------

### Create Agent API

Source: https://docs.zavu.dev/guides/ai-agents/setup

Programmatically create and configure an AI Agent for a sender using the Zavudev API. This endpoint allows for detailed customization of the agent's behavior, including the LLM provider, model, system prompt, and trigger channels.

```APIDOC
## POST /v1/senders/{senderId}/agent

### Description
Creates and configures an AI agent for a specific sender.

### Method
POST

### Endpoint
/v1/senders/{senderId}/agent

### Parameters
#### Path Parameters
- **senderId** (string) - Required - The ID of the sender to associate the agent with.

#### Query Parameters
None

#### Request Body
- **enabled** (boolean) - Required - Whether the agent is enabled.
- **provider** (string) - Required - The LLM provider (e.g., "openai", "anthropic", "google", "mistral", "zavu").
- **model** (string) - Required - The specific model to use (e.g., "gpt-4o-mini", "claude-3-5-haiku").
- **apiKey** (string) - Optional - The API key for the LLM provider. Not required for the "zavu" provider.
- **systemPrompt** (string) - Required - The instructions defining the agent's personality and behavior.
- **temperature** (number) - Optional - Controls the creativity of the agent's responses (0-2). Defaults to 0.7.
- **maxTokens** (integer) - Optional - The maximum length of the agent's response. Defaults to 500.
- **contextWindowMessages** (integer) - Optional - The number of previous messages to include in the context. Defaults to 10.
- **triggerOnChannels** (array of strings) - Optional - The channels on which the agent should be triggered (e.g., ["sms", "whatsapp"]).

### Request Example
```json
{
  "enabled": true,
  "provider": "openai",
  "model": "gpt-4o-mini",
  "apiKey": "sk-example-api-key",
  "systemPrompt": "You are a helpful customer support agent for Acme Corp. Be friendly and concise.",
  "temperature": 0.7,
  "maxTokens": 500,
  "contextWindowMessages": 10,
  "triggerOnChannels": ["sms", "whatsapp"]
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created agent.

#### Response Example
```json
{
  "id": "agent_xyz789"
}
```
```

--------------------------------

### CommonJS Support for Zavu SDK

Source: https://docs.zavu.dev/sdks/typescript/overview

Provides an example of how to import and initialize the Zavu SDK in a CommonJS environment.

```javascript
const Zavudev = require("@zavudev/sdk").default;

const zavu = new Zavudev({
  apiKey: process.env.ZAVUDEV_API_KEY,
});
```

--------------------------------

### Initialize Zavu Client with Environment Variable

Source: https://docs.zavu.dev/sdks/python/overview

Initializes the Zavu client using an API key stored in an environment variable.

```python
import os
from zavudev import Zavudev

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),
)
```

--------------------------------

### Update Agent Configuration (TypeScript, Python, cURL)

Source: https://docs.zavu.dev/guides/ai-agents/setup

Update an agent's system prompt, temperature, and model. This operation requires the agent's ID and accepts a payload with the desired configuration changes. The response will contain the updated agent object.

```typescript
const agent = await zavu.senders.agent.update("sender_abc123", {
    systemPrompt: "Updated system prompt...",
    temperature: 0.5,
    model: "gpt-4o", // Upgrade to more powerful model
  });
```

```python
agent = zavu.senders.agent.update(
    "sender_abc123",
    system_prompt="Updated system prompt...",
    temperature=0.5,
    model="gpt-4o",  # Upgrade to more powerful model
  )
```

```bash
curl -X PATCH https://api.zavu.dev/v1/senders/sender_abc123/agent \
    -H "Authorization: Bearer $ZAVU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "systemPrompt": "Updated system prompt...",
      "temperature": 0.5,
      "model": "gpt-4o"
    }'
```