Best Practices

Follow these best practices to build reliable, low-latency integrations with the AgentPhone API.

Voice latency

• Always use NDJSON streaming for voice webhooks. Return Content-Type: application/x-ndjson so TTS can start on the first chunk.
• Send an interim filler chunk like “Let me check on that” before calling your LLM or external API. The caller hears natural speech instead of silence.
• Stream speakable phrases as they become available. Buffer individual model tokens into natural speech, then send each non-final phrase as an NDJSON line with "interim": true. Omit interim (or set it to false) on the final chunk to finish the turn.
• Keep webhook response time under 5 seconds. If processing takes longer, stream an interim acknowledgement within the first second.
• Voice webhooks have a 30-second default timeout (configurable from 5–120 seconds per webhook). If your server doesn’t begin responding in time, the request is cancelled and the caller hears silence for that turn. This is especially important for tool-calling agents — always stream an interim chunk before running external API calls.

See the Calls guide for the full streaming response format, tool-calling examples, and troubleshooting tips.

Security

• Never expose API keys in client-side code or public repositories. Use environment variables.
• Always verify webhook signatures using the X-Webhook-Signature and X-Webhook-Timestamp headers to ensure requests are from AgentPhone.
• Check the timestamp — reject requests older than 5 minutes to prevent replay attacks.
• Use HTTPS for all webhook endpoints in production.
• Rotate API keys periodically and revoke unused keys.

See Webhooks > Security for verification code examples.

Webhook reliability

• Acknowledge text events quickly after durable enqueueing. Voice turns require speech in the response; an empty acknowledgement produces silence.
• Handle duplicate deliveries — use the X-Webhook-ID header for idempotency. Retries can cause the same event to be delivered multiple times.
• Know the event’s retry policy — non-voice agent.message deliveries have up to eight attempts. Other notifications have one attempt, and live voice turns have no delayed retry queue. See retry behavior.
• Log delivery IDs, status, and timing for debugging and audit purposes. Use GET /v1/webhooks/deliveries to monitor delivery status.

Pagination

Most list endpoints support offset-based pagination with limit and offset parameters. Message endpoints use cursor-based pagination with before and after timestamps.

Offset-based (agents, numbers, conversations, calls)

GET /v1/numbers?limit=20&offset=0

Cursor-based (messages)

GET /v1/numbers/:id/messages?limit=50&before=2025-01-15T12:00:00Z

Response format

{
  "data": [],
  "hasMore": true,
  "total": 42
}

Always check hasMore before fetching the next page. Use cursor-based pagination for time-ordered data as it’s more efficient than offset-based.

Performance

• Use webhooks instead of polling for real-time updates.
• Use SSE transcript streaming for live call monitoring — GET /v1/calls/:id/transcript/stream delivers turns in real time as a Server-Sent Events stream. No polling needed. See Calls > Stream transcript (SSE).
• Use cursor-based pagination (before/after) for loading message history.
• Cache frequently accessed data like phone number lists.
• Respect rate limits — implement exponential backoff for retries. Check the Retry-After header on 429 responses.

Error handling

• Always check response status before processing data.
• Retry reads with bounded backoff. Do not automatically retry sends, purchases, or calls after an ambiguous timeout or 5xx; they may already have executed.
• Log errors with context for debugging.
• Handle validation errors gracefully — check the details array for field-level errors.

See the Error Handling page for the full error response format and code examples.