Best Practices

Guidelines for building reliable, low-latency, and compliant integrations on the Voicebip platform.

Webhook Response Time

For BYOM (Bring Your Own Model) integrations, keep your webhook response time under 300ms. Your handler’s latency directly affects the caller’s experience.

• Pre-warm LLM connections. Initialize clients at startup, not per-request. Use connection pooling.
• Use streaming if your LLM supports it. Return the first sentence immediately rather than waiting for the full completion.
• Avoid database writes in the critical path. Respond first, then log asynchronously.
• Co-locate your server close to Voicebip’s API — EU or Africa regions are recommended for Nigerian traffic.

1
// Bad: synchronous database write before responding
2
app.post("/webhook", async (req, res) => {
3
  await db.insertEvent(req.body);   // 50-100ms wasted
4
  const reply = await llm.complete(req.body.payload.text);
5
  res.json({ text: reply, end_call: false });
6
});
7
8
// Good: respond first, log asynchronously
9
app.post("/webhook", async (req, res) => {
10
  const reply = await llm.complete(req.body.payload.text);
11
  res.json({ text: reply, end_call: false });
12
  db.insertEvent(req.body).catch(console.error);  // fire-and-forget
13
});

Nigerian Network Tips

Voicebip operates on NCC-licensed Nigerian carrier infrastructure. Understanding the MNO landscape helps you build more reliable voice and SMS integrations.

• MTN is the most reliable primary trunk. It has the highest call completion and SMS delivery rates nationwide.
• MNO failover is automatic with a 5-second budget. The failover chain is: MTN -> Glo -> Airtel -> 9mobile. Unknown prefixes default to MTN.
• Test with numbers from each MNO to ensure your application handles all carriers correctly.

NDPR Compliance

Voicebip operates under Nigeria’s Data Protection Regulation (NDPR). Follow these practices to stay compliant.

Recording Consent

• Obtain consent before recording. When recording_enabled is set to true on an agent, Voicebip automatically plays a consent prompt and uses a DTMF flow: press 1 to consent, press 2 to opt out. No response within 10 seconds defaults to no recording.
• Never enable recording_enabled without a consent flow. Recording calls without consent violates NDPR.

STOP Opt-Outs

• Honor STOP opt-outs. When a recipient sends STOP via SMS or WhatsApp, Voicebip automatically adds them to the workspace opt-out list. This is automatic — subsequent message attempts return 422 OPT_OUT_ENFORCED.

Data Retention

• Configure retention_days on your workspace to control how long call recordings and transcripts are stored across all agents. After the retention period, recordings and transcripts are permanently deleted.

$
curl -X PATCH "https://api.voicebip.com/v1/workspace" \
>
  -H "Authorization: Bearer pk_live_your_key" \
>
  -H "Content-Type: application/json" \
>
  -d '{"retention_days": 90}'

Data Processing Agreement

• Accept the DPA. Under NDPR, processing Nigerian personal data requires adequate safeguards, explicit user consent, and a documented Data Protection Impact Assessment. Voicebip handles infrastructure-level safeguards; you are responsible for obtaining user consent in your application.

Error Handling

Check error_code in Responses

Every Voicebip API error response includes a structured error envelope. Always check error_code rather than parsing the message string.

1
{
2
  "error_code": "RATE_LIMITED",
3
  "message": "Rate limit exceeded. Retry after 12 seconds.",
4
  "request_id": "req_abc123def456",
5
  "documentation_url": "https://docs.voicebip.com/errors/RATE_LIMITED"
6
}

Idempotent Webhook Handlers

Every webhook event includes a unique event_id. Use it to deduplicate events, since Voicebip’s retry mechanism (7 attempts with exponential backoff) may deliver the same event multiple times. The same event_id is used across all retries.

1
const processedEvents = new Set(); // Use Redis in production
2
3
app.post("/webhook", (req, res) => {
4
  const { event_id } = req.body;
5
6
  if (processedEvents.has(event_id)) {
7
    // Already processed — return 200 to stop retries
8
    return res.json({ status: "ok" });
9
  }
10
11
  processedEvents.add(event_id);
12
13
  // Process the event...
14
  res.json({ status: "ok" });
15
});

Handle 429 with Retry-After

When you receive an HTTP 429 response, read the Retry-After header and wait before retrying.

1
const response = await fetch("https://api.voicebip.com/v1/calls", {
2
  method: "POST",
3
  headers: {
4
    Authorization: `Bearer ${apiKey}`,
5
    "Content-Type": "application/json",
6
  },
7
  body: JSON.stringify(callPayload),
8
});
9
10
if (response.status === 429) {
11
  const retryAfter = parseInt(response.headers.get("Retry-After"), 10);
12
  console.log(`Rate limited. Retrying in ${retryAfter} seconds.`);
13
  await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
14
  // Retry the request...
15
}

Latency Optimization

Use Hosted AI Mode for Sub-500ms Turns

If sub-500ms turn times are critical (e.g., interactive IVR, real-time customer support), use hosted AI mode. Voicebip runs the AI provider inside its own infrastructure, eliminating the webhook round-trip.

Minimize Webhook Handler Processing

For BYOM integrations, the voice pipeline is:

Caller speaks -> STT transcribes -> Webhook to your server -> Your LLM call ->
Response back to Voicebip -> TTS synthesizes -> Caller hears response

Every millisecond in your webhook handler adds to the caller’s wait time. Optimize by pre-warming LLM connections, using the conversation_history field (Voicebip sends the last 20 turns so you do not need a database lookup), and setting aggressive timeouts on your LLM calls.

Keep conversation_history Under 20 Turns

Voicebip automatically trims conversation history to the last 20 turns in every BYOM webhook event. This keeps payloads small and LLM context windows efficient. You do not need to manage history trimming yourself.

Consider Gemini Live for Real-Time Audio Streaming

For the absolute lowest latency, consider using Voicebip’s hosted AI mode with Gemini 2.0 Flash Live. This mode streams audio bidirectionally, bypassing the traditional STT -> LLM -> TTS pipeline entirely, enabling near-real-time conversational AI.