> ## 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.

# Call The DialNexa API From TypeScript

> Call the DialNexa API from TypeScript and Node.js services with typed payloads, fetch, and clear error handling that matches the published OpenAPI spec.

The DialNexa API is reachable from any TypeScript or Node.js service using the standard `fetch` API (available natively in Node.js 18+ and on modern edge runtimes). There is no TypeScript-specific SDK package yet, the recommended pattern is a thin typed wrapper module in your own codebase that centralizes the base URL, authentication header, and error handling. The example below mirrors the operations published in [`/api-reference/openapi.json`](/docs/api-reference/openapi.json) and is a good starting point for production server code.

## When to use this

* **Server-side Node.js services** that trigger outbound calls from CRM events, scheduled jobs, or upstream webhooks.
* **Edge runtimes** (Cloudflare Workers, Vercel Edge Functions, Netlify Edge Functions) where you need a low-latency request path.
* **Internal tools and dashboards** built with Next.js, Remix, or similar frameworks where DialNexa operations run in route handlers.

Do not call this directly from a browser bundle. The `DIALNEXA_API_KEY` must stay server-side. For browser voice experiences, use the current [Web Calls](/docs/calls/web-calls) path. React and React Native packages are not released.

## Trigger A DialNexa Outbound Call From TypeScript

```ts theme={null}
const API_KEY = process.env.DIALNEXA_API_KEY;
const BASE_URL = "https://api.dialnexa.com/v1";

type CreateCallRequest = {
  agent_id: string;
  to_phone_number: string;
  from_phone_number?: string;
  metadata?: Record<string, unknown>;
};

type CreateCallResponse = {
  id: string;
  status: string;
  agent_id: string;
  to_phone_number: string;
  from_phone_number?: string;
  duration_sec?: number;
  created_at: string;
};

export async function createCall(payload: CreateCallRequest): Promise<CreateCallResponse> {
  const response = await fetch(`${BASE_URL}/calls`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${API_KEY}`,
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`DialNexa createCall failed (${response.status}): ${errorBody}`);
  }

  return response.json() as Promise<CreateCallResponse>;
}
```

Example usage:

```ts theme={null}
await createCall({
  agent_id: "agent_123",
  to_phone_number: "+14155550123",
  from_phone_number: "+14155559876",
  metadata: { campaign: "renewals", customer_name: "Priya Sharma" },
});
```

## Recommended patterns

* **Type every request and response.** The examples above declare explicit `CreateCallRequest` and `CreateCallResponse` types, keep this discipline so a wrong field name surfaces at compile time rather than at runtime.
* **Centralize the client.** Wrap the snippet above in a single module (for example `dialnexaClient.ts`) and import it from every route handler and worker.
* **Use environment variables for the API key.** Never inline keys in source. Make sure your bundler does not expose them to the client.
* **Set explicit timeouts.** Pass an `AbortSignal` from `AbortSignal.timeout(30_000)` if your runtime supports it.
* **Retry on transient failures only.** Retry HTTP 502/503/504 and network errors with exponential backoff. Do not retry 4xx responses, those indicate a payload that needs to be fixed. See [Errors](/docs/api-reference/errors).
* **Validate webhook deliveries.** For inbound events from DialNexa, verify the signing secret before trusting the payload. See [Webhook secrets](/docs/api-access/webhook-secrets).

<Note>
  This example is generated from the currently published schema in [`/api-reference/openapi.json`](/docs/api-reference/openapi.json): `agent_id` and `to_phone_number` are required.
</Note>

## Related pages

* [API Introduction](/docs/api-reference/introduction): base URLs, authentication, request and response shape.
* [Trigger a Call](/docs/api-reference/v1/calls/create): full OpenAPI schema for the operation above.
* [Errors](/docs/api-reference/errors): error format and codes returned by every endpoint.
* [Dynamic Variables](/docs/agents/dynamic-variables): injecting context into agent prompts via `metadata`.
* [Authentication](/docs/api-reference/authentication): how API keys are sent and verified.