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

# TypeScript and Python examples

> Copy complete v1 workflows for agents, calls, call listing, and signed webhooks.

These examples use the HTTP API directly. Set `DIALNEXA_API_KEY` in your shell and never put the key in browser code, source control, logs, or screenshots.

## Goal: create, publish, and call an agent

### TypeScript

```typescript theme={null}
const apiKey = process.env.DIALNEXA_API_KEY!;
const baseUrl = "https://api.dialnexa.com/v1";

async function request(path: string, init: RequestInit = {}) {
  const response = await fetch(`${baseUrl}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });
  const body = await response.json();
  if (!response.ok) throw new Error(`${response.status}: ${JSON.stringify(body)}`);
  return body;
}

const agent = await request("/agents", {
  method: "POST",
  body: JSON.stringify({
    title: "Appointment Assistant",
    language_id: "LANGUAGE_ID",
    voice_id: "VOICE_ID",
    prompt_text: "Confirm {{customer_name}}'s appointment.",
  }),
});

await request(`/agents/${agent.id}`, {
  method: "PATCH",
  body: JSON.stringify({ version_number: 1, is_published: true }),
});

const call = await request("/calls", {
  method: "POST",
  body: JSON.stringify({
    agent_id: agent.id,
    phone_number: "+919876543210",
    metadata: { customer_name: "Priya", correlation_id: "crm-8421" },
  }),
});
console.log(call.id);
```

### Python

```python theme={null}
import os
import requests

BASE_URL = "https://api.dialnexa.com/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['DIALNEXA_API_KEY']}",
    "Content-Type": "application/json",
}

agent_response = requests.post(
    f"{BASE_URL}/agents",
    headers=HEADERS,
    json={
        "title": "Appointment Assistant",
        "language_id": "LANGUAGE_ID",
        "voice_id": "VOICE_ID",
        "prompt_text": "Confirm {{customer_name}}'s appointment.",
    },
    timeout=30,
)
agent_response.raise_for_status()
agent = agent_response.json()

publish_response = requests.patch(
    f"{BASE_URL}/agents/{agent['id']}",
    headers=HEADERS,
    json={"version_number": 1, "is_published": True},
    timeout=30,
)
publish_response.raise_for_status()

call_response = requests.post(
    f"{BASE_URL}/calls",
    headers=HEADERS,
    json={
        "agent_id": agent["id"],
        "phone_number": "+919876543210",
        "metadata": {"customer_name": "Priya", "correlation_id": "crm-8421"},
    },
    timeout=30,
)
call_response.raise_for_status()
print(call_response.json()["id"])
```

## Goal: list and reconcile calls

```typescript theme={null}
const response = await fetch("https://api.dialnexa.com/v1/calls?agent_id=AGENT_ID", {
  headers: { Authorization: `Bearer ${process.env.DIALNEXA_API_KEY}` },
});
if (!response.ok) throw new Error(`List calls failed: ${response.status}`);
const calls = await response.json();
const matching = calls.find((call: any) => call.metadata?.correlation_id === "crm-8421");
```

```python theme={null}
response = requests.get(
    f"{BASE_URL}/calls",
    headers=HEADERS,
    params={"agent_id": agent["id"]},
    timeout=30,
)
response.raise_for_status()
matching = next(
    (call for call in response.json() if call.get("metadata", {}).get("correlation_id") == "crm-8421"),
    None,
)
```

## Goal: register and verify a webhook

```typescript theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

const secret = process.env.DIALNEXA_WEBHOOK_SECRET!;
const webhook = await request("/user-webhooks", {
  method: "POST",
  body: JSON.stringify({
    url: "https://example.com/webhooks/dialnexa",
    events: ["call.completed", "call.failed"],
    secret,
    is_active: true,
  }),
});

function verify(rawBody: Buffer, signature: string) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const supplied = Buffer.from(signature || "", "hex");
  const expectedBytes = Buffer.from(expected, "hex");
  return supplied.length === expectedBytes.length && timingSafeEqual(supplied, expectedBytes);
}
```

```python theme={null}
import hashlib
import hmac
import os

secret = os.environ["DIALNEXA_WEBHOOK_SECRET"]
webhook_response = requests.post(
    f"{BASE_URL}/user-webhooks",
    headers=HEADERS,
    json={
        "url": "https://example.com/webhooks/dialnexa",
        "events": ["call.completed", "call.failed"],
        "secret": secret,
        "is_active": True,
    },
    timeout=30,
)
webhook_response.raise_for_status()

def verify(raw_body: bytes, signature: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or "")
```

## Verify before production

* Replace every placeholder with an ID returned by the catalog or create operation.
* Run the agent flow against a test destination you control.
* Confirm the call through [Get Call](/docs/api-reference/v1/calls/get).
* Store webhook secrets in a secret manager and verify the raw body.
* Follow [Reliability and retries](/docs/api-reference/reliability) before adding automatic retries.