Integrate DialNexa APIs With AI Coding Agents

Use this guide to integrate DialNexa APIs with AI coding agents in an existing product. The prompts on this page tell Codex, Cursor, or Claude Code to inspect your repository, use the current DialNexa v1 contract, implement the requested server-side flow, add tests, and report the manual steps that remain.

Review every change before deployment. The prompts do not authorize an AI coding agent to place a real call, start a batch, purchase a phone number, delete a resource, or change production.

Integrate DialNexa APIs With AI Coding Agents

An AI coding agent can complete most repository work for a DialNexa integration, including the HTTP client, application wiring, webhook handler, tests, configuration examples, and developer notes. A person still controls secrets, DialNexa workspace configuration, production deployment, and billable tests.

The coding agent can	You still control
Inspect the repository and follow its conventions.	The product goal and expected user experience.
Read the current DialNexa docs and OpenAPI schema.	API-key creation, rotation, and secret-manager access.
Add a server-side DialNexa client and product flow.	Production credentials and deployment approval.
Add mocked tests for success and failure cases.	Approval for real calls, batches, purchases, and deletions.
Add signed webhook verification when required.	The final test destination and review of live results.

When To Use This Guide

Use these prompts when you already have a codebase and want to add a specific DialNexa API workflow. Good examples include:

Place an outbound call after a lead submits a form.
Save a DialNexa call ID against a CRM record.
Receive a webhook delivery when a call that was not placed directly by a batch call ends.
Create or update agents from an internal backend service.
Add leads to a workflow from your application.
Start a batch call from an approved server-side process.

If you only want to test the API manually, start with the API Quickstart. If you need a reusable HTTP pattern before involving a coding agent, see the TypeScript and Python examples.

Before You Begin

Open the application repository in Codex, Cursor, or Claude Code.
Check that the coding agent can read files, edit files, and run your test commands.
Write down the application event that starts the flow and the result your product should store or display.
Create a DialNexa API key under Settings > API Keys, but do not paste the key into the prompt or chat.
Decide whether the first run should stop after mocked tests or include a read-only request to your DialNexa workspace.

DialNexa does not currently publish a first-party server SDK. The coding agent should use your language’s HTTP client and the current OpenAPI document.

Step 1: Describe The Integration Outcome

Replace the bracketed fields inside your chosen prompt. Describe product behavior rather than naming an endpoint alone.

Goal: [What should the product do with DialNexa?]
Trigger: [What application event starts the flow?]
Inputs: [Which existing fields should be sent?]
Expected result: [What should be saved, displayed, or triggered afterward?]
Known DialNexa resources: [Agent ID, workflow ID, or "discover from configuration"]
Deployment target: [Local, staging, production, or "not decided"]

For example:

Goal: Call a new sales lead and save the final call outcome in our CRM.
Trigger: A lead completes the demo request form.
Inputs: Lead ID, name, E.164 phone number, company, and requested product.
Expected result: Save the DialNexa call ID immediately, then update the lead when a signed call-ended webhook arrives, or from Get Call Details if no delivery arrives.
Known DialNexa resources: Read the agent ID from server configuration.
Deployment target: Staging first.

Step 2: Copy The Prompt For Your Coding Agent

Each prompt is complete and can be pasted into a new agent session opened at the root of your application repository.

Codex
Cursor
Claude Code

Read every applicable AGENTS.md file before making changes. Work from the repository root and complete this DialNexa integration from codebase inspection through local verification. Do not stop after producing a plan unless a missing product decision would materially change the implementation.

INTEGRATION BRIEF

Goal: [What should the product do with DialNexa?]
Trigger: [What application event starts the flow?]
Inputs: [Which existing fields should be sent?]
Expected result: [What should be saved, displayed, or triggered afterward?]
Known DialNexa resources: [Agent ID, workflow ID, or "discover from configuration"]
Deployment target: [Local, staging, production, or "not decided"]

SOURCE OF TRUTH

Use the current DialNexa documentation and OpenAPI document as the authority:
- https://dialnexa.com/docs/llms.txt
- https://dialnexa.com/docs/api-reference/introduction
- https://dialnexa.com/docs/api-reference/openapi.json
- The relevant authentication, reliability, error, webhook, and endpoint pages linked from the API reference

Use https://api.dialnexa.com/v1 as the API base URL. Do not use retired unversioned routes. Do not invent endpoints, fields, enum values, response shapes, rate limits, idempotency headers, or an unofficial DialNexa SDK.

IMPLEMENTATION WORKFLOW

1. Inspect the repository before editing.
   - Identify the framework, runtime, package manager, test commands, HTTP-client conventions, configuration system, persistence layer, and existing service boundaries.
   - Find the application code that owns the trigger and expected result in the integration brief.
   - Reuse established patterns when they are suitable.

2. State the implementation path in a short update, then make the changes.
   - List the main files or modules you expect to touch.
   - Make reasonable, reversible assumptions when the repository answers a question.
   - Ask one focused question only when a missing decision would materially change user-visible behavior or data ownership.

3. Build a small server-side DialNexa client or service.
   - Read the API key from DIALNEXA_API_KEY.
   - Send Authorization: Bearer <key> on each request.
   - Keep the key out of browser bundles, source control, logs, errors, test fixtures, and screenshots.
   - Add DIALNEXA_API_KEY to the appropriate example environment file with an empty or obvious placeholder value.
   - Centralize the base URL, authentication, JSON parsing, timeouts, and DialNexa error parsing.
   - Surface the HTTP status, message, and data.code (when present) from an API failure. Calls, batch calls, voices, languages, and LLMs return only message and data; other endpoints also return statusCode, error, success, and errors.

4. Implement the product flow from the integration brief.
   - Use only request fields and response fields present in the current OpenAPI operation.
   - Validate user-controlled input before making the request.
   - Treat phone numbers as E.164 values when the operation requires a phone number.
   - Store returned DialNexa resource IDs as soon as a create request succeeds.
   - For outbound calls, store the returned call ID against the application record and use it to reconcile.
   - Keep DialNexa calls behind an application service or server route. Never call DialNexa with a workspace API key from browser code.

5. Apply operation-specific retry behavior.
   - Add capped exponential backoff only for eligible read operations after network errors, 429 responses, or transient 5xx responses. Each API key is limited to 150 requests per 60 seconds, counted separately for each endpoint.
   - Honor Retry-After when the response includes it.
   - Do not blindly retry resource creation, state transitions, phone-number purchases, batch calls, or outbound calls.
   - After an uncertain write, read or list the affected resource and reconcile using the stored resource IDs before deciding whether another request is safe.

6. Implement webhooks when the integration brief requires final call results.
   - Read the secret from DIALNEXA_WEBHOOK_SECRET.
   - Verify x-nexa-signature against the raw request body using the exact algorithm and header format documented by DialNexa.
   - Reject a missing or invalid signature before parsing, storing, or acting on the event.
   - Make processing safe for duplicate deliveries using the identifiers and status fields available in the documented payload.
   - Add DIALNEXA_WEBHOOK_SECRET to the example environment file without a real value.

7. Add focused automated tests.
   - Mock DialNexa network calls in normal test runs.
   - Assert the method, /v1 URL, authorization header, request body, response mapping, and secret redaction.
   - Cover the success path, a documented validation error, 401 authentication failure, timeout behavior, and retry classification.
   - For webhooks, cover a valid signature, invalid signature, raw-body handling, and duplicate processing.
   - Do not weaken or delete unrelated tests.

8. Verify the implementation.
   - Run the repository's formatter, type checker, linter, and relevant test suite.
   - Fix failures caused by the changes.
   - If DIALNEXA_API_KEY is already configured and network access is available, you may make one read-only GET request such as GET /languages to verify authentication.
   - Do not ask me to reveal an API key in chat.
   - Do not place a real call, start a batch, purchase a number, delete a resource, publish an agent, or change production without my explicit approval for that exact action.

9. Finish with a concise handoff.
   - Summarize the product flow and files changed.
   - List configuration variables without printing their values.
   - Report every command run and whether it passed.
   - Give exact manual staging verification steps.
   - Separate mocked verification from live DialNexa verification.
   - List assumptions and remaining blockers.

A successful create response means DialNexa accepted the operation. It does not prove that a recipient answered a call or that an asynchronous workflow completed. Verify the final state through the documented GET operation or signed webhook.

Work in Cursor Agent mode from the repository root. Read the applicable .cursor/rules files and AGENTS.md before making changes. Complete this DialNexa integration from codebase inspection through local verification. Do not stop after producing a plan unless a missing product decision would materially change the implementation.

INTEGRATION BRIEF

Goal: [What should the product do with DialNexa?]
Trigger: [What application event starts the flow?]
Inputs: [Which existing fields should be sent?]
Expected result: [What should be saved, displayed, or triggered afterward?]
Known DialNexa resources: [Agent ID, workflow ID, or "discover from configuration"]
Deployment target: [Local, staging, production, or "not decided"]

SOURCE OF TRUTH

Use the current DialNexa documentation and OpenAPI document as the authority:
- https://dialnexa.com/docs/llms.txt
- https://dialnexa.com/docs/api-reference/introduction
- https://dialnexa.com/docs/api-reference/openapi.json
- The relevant authentication, reliability, error, webhook, and endpoint pages linked from the API reference

Use https://api.dialnexa.com/v1 as the API base URL. Do not use retired unversioned routes. Do not invent endpoints, fields, enum values, response shapes, rate limits, idempotency headers, or an unofficial DialNexa SDK.

IMPLEMENTATION WORKFLOW

1. Inspect the repository before editing.
   - Identify the framework, runtime, package manager, test commands, HTTP-client conventions, configuration system, persistence layer, and existing service boundaries.
   - Find the application code that owns the trigger and expected result in the integration brief.
   - Reuse established patterns when they are suitable.

2. State the implementation path in a short update, then make the changes.
   - List the main files or modules you expect to touch.
   - Make reasonable, reversible assumptions when the repository answers a question.
   - Ask one focused question only when a missing decision would materially change user-visible behavior or data ownership.

3. Build a small server-side DialNexa client or service.
   - Read the API key from DIALNEXA_API_KEY.
   - Send Authorization: Bearer <key> on each request.
   - Keep the key out of browser bundles, source control, logs, errors, test fixtures, and screenshots.
   - Add DIALNEXA_API_KEY to the appropriate example environment file with an empty or obvious placeholder value.
   - Centralize the base URL, authentication, JSON parsing, timeouts, and DialNexa error parsing.
   - Surface the HTTP status, message, and data.code (when present) from an API failure. Calls, batch calls, voices, languages, and LLMs return only message and data; other endpoints also return statusCode, error, success, and errors.

4. Implement the product flow from the integration brief.
   - Use only request fields and response fields present in the current OpenAPI operation.
   - Validate user-controlled input before making the request.
   - Treat phone numbers as E.164 values when the operation requires a phone number.
   - Store returned DialNexa resource IDs as soon as a create request succeeds.
   - For outbound calls, store the returned call ID against the application record and use it to reconcile.
   - Keep DialNexa calls behind an application service or server route. Never call DialNexa with a workspace API key from browser code.

5. Apply operation-specific retry behavior.
   - Add capped exponential backoff only for eligible read operations after network errors, 429 responses, or transient 5xx responses. Each API key is limited to 150 requests per 60 seconds, counted separately for each endpoint.
   - Honor Retry-After when the response includes it.
   - Do not blindly retry resource creation, state transitions, phone-number purchases, batch calls, or outbound calls.
   - After an uncertain write, read or list the affected resource and reconcile using the stored resource IDs before deciding whether another request is safe.

6. Implement webhooks when the integration brief requires final call results.
   - Read the secret from DIALNEXA_WEBHOOK_SECRET.
   - Verify x-nexa-signature against the raw request body using the exact algorithm and header format documented by DialNexa.
   - Reject a missing or invalid signature before parsing, storing, or acting on the event.
   - Make processing safe for duplicate deliveries using the identifiers and status fields available in the documented payload.
   - Add DIALNEXA_WEBHOOK_SECRET to the example environment file without a real value.

7. Add focused automated tests.
   - Mock DialNexa network calls in normal test runs.
   - Assert the method, /v1 URL, authorization header, request body, response mapping, and secret redaction.
   - Cover the success path, a documented validation error, 401 authentication failure, timeout behavior, and retry classification.
   - For webhooks, cover a valid signature, invalid signature, raw-body handling, and duplicate processing.
   - Do not weaken or delete unrelated tests.

8. Verify the implementation.
   - Run the repository's formatter, type checker, linter, and relevant test suite.
   - Fix failures caused by the changes.
   - If DIALNEXA_API_KEY is already configured and network access is available, you may make one read-only GET request such as GET /languages to verify authentication.
   - Do not ask me to reveal an API key in chat.
   - Do not place a real call, start a batch, purchase a number, delete a resource, publish an agent, or change production without my explicit approval for that exact action.

9. Finish with a concise handoff.
   - Summarize the product flow and files changed.
   - List configuration variables without printing their values.
   - Report every command run and whether it passed.
   - Give exact manual staging verification steps.
   - Separate mocked verification from live DialNexa verification.
   - List assumptions and remaining blockers.

A successful create response means DialNexa accepted the operation. It does not prove that a recipient answered a call or that an asynchronous workflow completed. Verify the final state through the documented GET operation or signed webhook.

Work from the repository root. Read the applicable CLAUDE.md files before making changes. If the repository contains AGENTS.md and CLAUDE.md does not already import it, read AGENTS.md as project guidance too. Complete this DialNexa integration from codebase inspection through local verification. Do not stop after producing a plan unless a missing product decision would materially change the implementation.

INTEGRATION BRIEF

Goal: [What should the product do with DialNexa?]
Trigger: [What application event starts the flow?]
Inputs: [Which existing fields should be sent?]
Expected result: [What should be saved, displayed, or triggered afterward?]
Known DialNexa resources: [Agent ID, workflow ID, or "discover from configuration"]
Deployment target: [Local, staging, production, or "not decided"]

SOURCE OF TRUTH

Use the current DialNexa documentation and OpenAPI document as the authority:
- https://dialnexa.com/docs/llms.txt
- https://dialnexa.com/docs/api-reference/introduction
- https://dialnexa.com/docs/api-reference/openapi.json
- The relevant authentication, reliability, error, webhook, and endpoint pages linked from the API reference

Use https://api.dialnexa.com/v1 as the API base URL. Do not use retired unversioned routes. Do not invent endpoints, fields, enum values, response shapes, rate limits, idempotency headers, or an unofficial DialNexa SDK.

IMPLEMENTATION WORKFLOW

1. Inspect the repository before editing.
   - Identify the framework, runtime, package manager, test commands, HTTP-client conventions, configuration system, persistence layer, and existing service boundaries.
   - Find the application code that owns the trigger and expected result in the integration brief.
   - Reuse established patterns when they are suitable.

2. State the implementation path in a short update, then make the changes.
   - List the main files or modules you expect to touch.
   - Make reasonable, reversible assumptions when the repository answers a question.
   - Ask one focused question only when a missing decision would materially change user-visible behavior or data ownership.

3. Build a small server-side DialNexa client or service.
   - Read the API key from DIALNEXA_API_KEY.
   - Send Authorization: Bearer <key> on each request.
   - Keep the key out of browser bundles, source control, logs, errors, test fixtures, and screenshots.
   - Add DIALNEXA_API_KEY to the appropriate example environment file with an empty or obvious placeholder value.
   - Centralize the base URL, authentication, JSON parsing, timeouts, and DialNexa error parsing.
   - Surface the HTTP status, message, and data.code (when present) from an API failure. Calls, batch calls, voices, languages, and LLMs return only message and data; other endpoints also return statusCode, error, success, and errors.

4. Implement the product flow from the integration brief.
   - Use only request fields and response fields present in the current OpenAPI operation.
   - Validate user-controlled input before making the request.
   - Treat phone numbers as E.164 values when the operation requires a phone number.
   - Store returned DialNexa resource IDs as soon as a create request succeeds.
   - For outbound calls, store the returned call ID against the application record and use it to reconcile.
   - Keep DialNexa calls behind an application service or server route. Never call DialNexa with a workspace API key from browser code.

5. Apply operation-specific retry behavior.
   - Add capped exponential backoff only for eligible read operations after network errors, 429 responses, or transient 5xx responses. Each API key is limited to 150 requests per 60 seconds, counted separately for each endpoint.
   - Honor Retry-After when the response includes it.
   - Do not blindly retry resource creation, state transitions, phone-number purchases, batch calls, or outbound calls.
   - After an uncertain write, read or list the affected resource and reconcile using the stored resource IDs before deciding whether another request is safe.

6. Implement webhooks when the integration brief requires final call results.
   - Read the secret from DIALNEXA_WEBHOOK_SECRET.
   - Verify x-nexa-signature against the raw request body using the exact algorithm and header format documented by DialNexa.
   - Reject a missing or invalid signature before parsing, storing, or acting on the event.
   - Make processing safe for duplicate deliveries using the identifiers and status fields available in the documented payload.
   - Add DIALNEXA_WEBHOOK_SECRET to the example environment file without a real value.

7. Add focused automated tests.
   - Mock DialNexa network calls in normal test runs.
   - Assert the method, /v1 URL, authorization header, request body, response mapping, and secret redaction.
   - Cover the success path, a documented validation error, 401 authentication failure, timeout behavior, and retry classification.
   - For webhooks, cover a valid signature, invalid signature, raw-body handling, and duplicate processing.
   - Do not weaken or delete unrelated tests.

8. Verify the implementation.
   - Run the repository's formatter, type checker, linter, and relevant test suite.
   - Fix failures caused by the changes.
   - If DIALNEXA_API_KEY is already configured and network access is available, you may make one read-only GET request such as GET /languages to verify authentication.
   - Do not ask me to reveal an API key in chat.
   - Do not place a real call, start a batch, purchase a number, delete a resource, publish an agent, or change production without my explicit approval for that exact action.

9. Finish with a concise handoff.
   - Summarize the product flow and files changed.
   - List configuration variables without printing their values.
   - Report every command run and whether it passed.
   - Give exact manual staging verification steps.
   - Separate mocked verification from live DialNexa verification.
   - List assumptions and remaining blockers.

A successful create response means DialNexa accepted the operation. It does not prove that a recipient answered a call or that an asynchronous workflow completed. Verify the final state through the documented GET operation or signed webhook.

Step 3: Review The Result

Before deploying the generated integration, confirm each item below.

The DialNexa API key is read only by server-side code.
Every API path uses https://api.dialnexa.com/v1.
Request and response fields match the current OpenAPI document.
Normal automated tests use mocked HTTP responses and do not place calls.
Billable or state-changing requests are not retried blindly.
Outbound calls store the returned call ID against the application record.
Webhook signatures are checked against the raw body before JSON parsing.
Logs redact API keys, webhook secrets, phone numbers, and sensitive metadata.
The coding agent reports which checks were mocked and which used the live API.

For a real outbound test, use a destination you control and confirm that its country and prefix are enabled under Workspace Settings > Telephony. A 201 response only confirms that DialNexa accepted the call request. Use Get Call Details or a signed webhook to verify the final result.

Troubleshooting AI-Generated Integrations

Problem	What to do
The coding agent invents a DialNexa package.	Remove it and direct the agent to the HTTP API and OpenAPI document.
The API key appears in frontend code.	Stop the review. Move the request behind a server route and rotate the exposed key.
The agent uses an unversioned route.	Replace it with the documented `/v1` operation and recheck the request schema.
The agent retries `POST /calls` after a timeout.	Reconcile using the stored call ID, or list recent calls for the agent and time window, before another attempt.
The webhook handler parses JSON before verification.	Capture the raw body and verify `x-nexa-signature` before parsing or processing it.
The agent stops after a plan.	Confirm that Agent mode and file-editing tools are enabled, then ask it to continue through implementation and tests.
Mocked tests pass but the live read fails with `401`.	Confirm the full `key_id:secret` value is stored in `DIALNEXA_API_KEY` for the intended workspace.
A call request fails with `403`.	Check KYC, Telephony coverage for the destination, and the workspace’s DND list.
A call request fails with `402`.	Top up the wallet, or wait for the monthly spend cap to reset or have it raised.

What End-To-End Means Here

The prompt is complete when the coding agent has implemented the repository changes, passed the relevant local checks, and given you exact staging verification steps. Production deployment and any real, billable action remain separate approvals.

API Quickstart

Create an agent, publish it, place one call, and read the result with direct API requests.

API Fundamentals

Authenticate requests, paginate responses, handle errors, and retry safely.

Webhooks

Verify signed events and process asynchronous outcomes.

TypeScript And Python Examples

Review complete HTTP patterns for calls and signed webhooks.

Overview

Endpoints

Integrate DialNexa APIs With AI Coding Agents