API documentation

Voice order confirmation: integration guide

আপনি অর্ডার পাঠাবেন, আমরা কল করব, ফলাফল ফিরে যাবে আপনার সিস্টেমে।

You POST us an order. We call the customer, confirm the order in Bangla, and POST the result back to you. On your side you need one queued job and one route.

No code: Oporanno shops. If your shop is on Oporanno, connect your own Sworborno account in the dashboard under Settings, Ai Call, using your Sworborno API key and the webhook address Oporanno shows. New orders get a Bangla confirmation call from your shop's Sworborno balance, with the result on the order in Oporanno. See how it works on Oporanno.

Base URL: https://www.sworborno.com/api/v1 Auth: every request carries your API key. Keep it in .env, never in git.

Authorization: Bearer vk_live_xxxxxxxxxxxxxxxxxxxx

The key is the account. Every request counts toward the company the key belongs to. You never send an account id, so there is nothing to get wrong. Calls made for your account always show your own dedicated number as caller ID, and no other company on the platform can call from it.

Copy-ready examples in curl, Python, Node.js, PHP and Laravel, including a webhook receiver that checks the signature, are on GitHub: AI voice agent API examples for Bangladesh.


1. Send us an order

POST /integrations/call-requests            → 202 Accepted
{
  "external_id": "10432",
  "phone": "01798XXXXXX",
  "context": {
    "customer_name": "Rahim Uddin",
    "order_id": "10432",
    "total": 1450,
    "payment_method": "cod",
    "address": "House 12, Road 4, Dhanmondi, Dhaka",
    "items": [
      { "name": "Cotton Shirt", "qty": 2, "price": 650 },
      { "name": "Delivery", "qty": 1, "price": 150 }
    ]
  }
}
  • external_id: your order id, used as the idempotency key. If you send it twice, you get the first request back and the customer is not called again, so retries are safe. It is scoped to your account, so another company's 10432 never clashes with yours.
  • context: free-form JSON. The agent can answer questions from whatever you put here, so send what a support person would want on screen.
  • assistant_id: only needed if your account has more than one assistant.
CodeMeaning
202Accepted (the response is the same for a first send and a retry)
401Bad, missing or revoked API key
400 / 404assistant_id is missing when it is needed / is not yours
422Bad payload. The response names the field. Numbers we cannot dial fail here, not silently later
429Rate limited; back off and retry

Laravel: send from a queued job, never from the checkout controller

// config/services.php
'voice' => [
    'url'    => env('VOICE_API_URL'),
    'key'    => env('VOICE_API_KEY'),
    'secret' => env('VOICE_WEBHOOK_SECRET'),
],
// app/Jobs/RequestConfirmationCall.php
class RequestConfirmationCall implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public $tries = 3;
    public $backoff = [30, 120];

    public function __construct(public Order $order) {}

    public function handle(): void
    {
        Http::withToken(config('services.voice.key'))
            ->timeout(10)
            ->post(config('services.voice.url').'/integrations/call-requests', [
                'external_id' => (string) $this->order->id,
                'phone'       => $this->order->phone,
                'context'     => [
                    'customer_name'  => $this->order->customer_name,
                    'order_id'       => (string) $this->order->id,
                    'total'          => $this->order->total,
                    'payment_method' => $this->order->payment_method,
                    'address'        => $this->order->full_address,
                    'items'          => $this->order->items->map(fn ($i) => [
                        'name' => $i->name, 'qty' => $i->quantity, 'price' => $i->price,
                    ])->all(),
                ],
            ])->throw();
    }
}

// wherever the order is created:
RequestConfirmationCall::dispatch($order);

Two things often catch people out. First, QUEUE_CONNECTION must not be sync in production, because that puts our network call inside your checkout. Second, you need ->throw(). Without it, a failed POST is silently dropped and the customer is never called.


2. Receive the result

When the call reaches an outcome, we POST once to a URL you give us.

Confirmed:

{
  "event": "call.result",
  "order_id": "10432",
  "status": "confirmed",
  "reason": null,
  "summary": "Order and address confirmed on the call.",
  "address": {
    "original": "House 12, Road 4, Dhanmondi, Dhaka",
    "thana": "ধানমন্ডি",
    "zilla": "ঢাকা",
    "full": "House 12, Road 4, Dhanmondi, Dhaka, ধানমন্ডি, ঢাকা"
  },
  "attempt": 1,
  "duration_seconds": 61,
  "completed_at": "2026-08-21T09:56:57+00:00",
  "balance_seconds": 5279,
  "available_seconds": 5279
}

Hold:

{
  "event": "call.result",
  "order_id": "10432",
  "status": "hold",
  "reason": "cancelled",
  "summary": "The customer said they no longer want the order.",
  "address": { "original": "House 12, Road 4, Dhanmondi, Dhaka",
               "thana": null, "zilla": null,
               "full": "House 12, Road 4, Dhanmondi, Dhaka" },
  "attempt": 1,
  "duration_seconds": 38,
  "completed_at": "2026-08-21T10:02:11+00:00",
  "balance_seconds": 5241,
  "available_seconds": 5241
}

status: the only field your code should branch on. It has two values, on purpose.

StatusWhat your system should do
confirmedCustomer confirmed; address collected. Ship it.
holdAnything else. Put it in front of a person. Never auto-cancel.

reason says why an order is on hold. Show it to the person reviewing it, but do not branch on it:

ReasonWhat happened
cancelledCustomer does not want it
modifiedWants a change; see summary
wrong_numberNot the customer
address_incompleteConfirmed, but hung up before the address finished
unclearThe call ended without a clear answer, including "call me back later"
no_answerNobody picked up on any of the allowed attempts
call_failedThe call could not be made, or could not continue
abusiveThe person was abusive; think about not calling this number again
ran_longWent past the platform's length limit without an outcome

address

original is exactly what you sent, and it is never overwritten. thana and zilla are what the customer said, with the district checked where possible. For example, "চিটাগাং (চট্টগ্রাম)" means the customer said the first and we matched it to the second; both are kept. full is the courier label line, already joined.

duration_seconds, balance_seconds, available_seconds

Added 10 September 2026. Nothing was removed or moved, so an integration that ignores unknown keys needs no change.

  • duration_seconds: the billed length of the call behind this result, in whole seconds. It is null when no attempt connected (call_failed, or no_answer after every attempt), and, rarely, when a call connected but could not be measured. We never guess a length.
  • balance_seconds / available_seconds: your account balance after this call was charged. They mean the same as in GET /integrations/balance (§4). Base your checks on available_seconds. In the rare case that our own reconciliation check resends a result hours later, these show the balance at the time of the resend.

We save the result as soon as the call reaches a decision, while the customer is still on the line. The POST goes out after the call has ended and been billed, usually ten to twenty seconds later, so all three figures are final when you read them. They stay fixed with the result: a retried delivery carries the same numbers as the first attempt, not the current balance.

If you poll instead, GET /integrations/call-requests/{id} returns the same duration_seconds.

The route: verify, skip duplicates, answer fast

Put it in routes/api.php. The CSRF check in web.php rejects our POST with a 419. Every delivery carries three headers:

HeaderWhat it is
X-SignatureHMAC-SHA256 of "{timestamp}.{raw body}" with your secret
X-Webhook-TimestampUnix seconds, signed with the body so a captured POST expires
X-Webhook-IdThe same on every retry of one result; use it to skip duplicates
public function handle(Request $request)
{
    $ts       = $request->header('X-Webhook-Timestamp', '');
    $expected = hash_hmac('sha256', $ts.'.'.$request->getContent(),
                          config('services.voice.secret'));
    abort_unless(hash_equals($expected, $request->header('X-Signature', '')), 401);
    abort_if(abs(time() - (int) $ts) > 300, 401);   // no replays

    // At-least-once delivery: the same result can arrive twice. Do the work once.
    if (WebhookReceipt::where('webhook_id', $request->header('X-Webhook-Id'))->exists()) {
        return response()->noContent();
    }
    WebhookReceipt::create(['webhook_id' => $request->header('X-Webhook-Id')]);

    // Two kinds of message arrive here: call results and account events.
    if ($request->input('event') === 'balance.low') {
        Log::warning('Voice agent balance low', $request->only('balance_minutes'));
        // e.g. notify ops; calls stop when the balance is empty.
        return response()->noContent();
    }

    $order = Order::findOrFail($request->input('order_id'));
    match ($request->input('status')) {
        'confirmed' => $order->update([
            'status'         => 'confirmed',
            'shipping_thana' => $request->input('address.thana'),
            'shipping_zilla' => $request->input('address.zilla'),
        ]),
        default => $order->update([
            'status'      => 'needs_review',
            'hold_reason' => $request->input('reason'),
            'call_note'   => $request->input('summary'),
        ]),
    };
    return response()->noContent();   // any non-2xx and we retry
}

Delivery guarantees: we save the result on our side before the first attempt. If your server returns a non-2xx or times out, we retry immediately, then after 30s, 2m, 10m, 30m, 2h and 6h (about 9 hours in all). So a deploy or restart on your side loses nothing. If every attempt fails, we flag it and can resend it by hand.

Calls are recorded on our server in case an order is disputed. Recordings are not linked here; ask us with the order id. Telling your customers that calls are recorded is your job.


3. Check, and cancel

GET    /integrations/call-requests/{external_id}    → status + outcome, by your id
DELETE /integrations/call-requests/{external_id}    → withdraw before the call

What GET returns:

{
  "id": "5e0b…", "external_id": "10432",
  "status": "done",
  "outcome": "confirmed",
  "outcome_details": { "reason": "", "thana": "ধানমন্ডি", "zilla": "ঢাকা",
                       "summary": "Order and address confirmed on the call." },
  "attempts": 1, "to_number": "01798XXXXXX",
  "created_at": "2026-08-21T09:55:40+00:00",
  "completed_at": "2026-08-21T09:56:57+00:00",
  "duration_seconds": 61,
  "error": null
}
  • status: queued → calling → done, or cancelled after a DELETE. (A few old rows have failed; treat it as a hold.)
  • outcome: null until done, then confirmed or hold, the same word the webhook uses. outcome_details holds reason, thana, zilla and summary. This endpoint has no address.full; build it yourself from your own address plus thana and zilla.
  • attempts: how many times we have dialled so far. If status is queued and attempts is 1 or more, nobody answered and another attempt is scheduled.
  • error: a short reason in plain words when no call could be placed or the phone was not reached, and null otherwise. You can match these fixed sentences:
Reasonerror
Not reachedThe phone was not reached: no answer, switched off or out of coverage.
BusyThe phone was busy.
Check the numberThe number could not be called. Check that the phone number is correct.
No minutesThis account has no calling minutes left. Top up the balance to place calls.
Do not callThis number is on the account's do-not-call list.
Customer called backCancelled: the customer called back first.
Could not placeThe call could not be placed.

Cancel when the customer cancels, or when your staff confirm the order by hand. If the phone is already ringing, it stops. A request that already has an outcome comes back unchanged.

A webhook can arrive more than once, and in rare cases it can be missed. Run this every hour so no order slips through:

Schedule::call(function () {
    Order::where('status', 'awaiting_confirmation')
        ->where('created_at', '<', now()->subHours(2))
        ->each(function ($order) {
            $r = Http::withToken(config('services.voice.key'))
                ->get(config('services.voice.url')."/integrations/call-requests/{$order->id}");
            if ($r->ok() && $r->json('outcome') !== null) {
                ProcessCallResult::dispatch($order, $r->json());
            }
        });
})->hourly();

4. Balance

Calls stop when the account runs out of minutes, so keep an eye on the balance. You can ask for it, or we can tell you. Both are authenticated and signed like everything else:

GET /integrations/balance
→ {"balance_seconds": 5340, "balance_minutes": "89m 0s",
   "available_seconds": 5220, "low_balance_threshold_seconds": 600}

available_seconds leaves out what calls in progress may still use, so base your checks on it, not on balance_seconds. Every call.result webhook also carries both figures as the balance after that call (§2). If your system handles results, it already sees the balance change without polling.

When a call takes the balance below the threshold, your webhook gets this event once, with the same signing and the same duplicate-check id:

{
  "event": "balance.low",
  "balance_seconds": 540,
  "balance_minutes": "9m 0s",
  "threshold_seconds": 600,
  "at": "2026-08-22T10:15:00+00:00"
}

You get one event each time the balance drops below the threshold. A top-up above the threshold resets it.


5. Voiceover (text to speech)

The same key turns text into speech. Voiceover must be on for your account, and the account must have been topped up at least once. One minute of audio uses 75 seconds of balance (৳5 a minute). You pay for the exact length of the audio; a voiceover that fails costs nothing.

First, list the voices. Each one has a short sample you can play:

GET /integrations/tts/voices
→ [{"id": "3f0c…", "name": "Nadia", "language": "bn", "gender": "female",
    "description": "Warm and clear", "preview_url": "https://…/preview.mp3?v=…",
    "preview_seconds": 9.4, "chars_per_minute": 780}]

Then send the text, up to 20,000 characters:

POST /integrations/tts
{"voice_id": "3f0c…", "text": "আপনার অর্ডারটি আজ পাঠানো হয়েছে।", "format": "mp3"}
  • Up to 2,000 characters: the answer is the audio file itself (audio/mpeg, or audio/wav with "format": "wav"). The headers X-Voiceover-Id, X-Audio-Seconds and X-Charged-Seconds describe it.
  • Longer text (or a short one that takes more than 90 seconds): 202 with a job. Ask for it until status is done, then download the file:
GET /integrations/tts/{id}
→ {"id": "8b21…", "status": "processing", "characters": 6400, "charged_seconds": 260, …}

GET /integrations/tts/{id}/audio?format=mp3      (or ?format=wav)

status is queued, processing, done, failed or expired. While a job runs, charged_seconds shows the estimate we hold; when it is done, the exact charge. Files are kept for 30 days.

StatusMeaning
402Not enough balance, or the account has never been topped up
403Voiceover is not on for this account
404No such voice, or no such voiceover
409The audio is not ready yet
410The voiceover failed, or it is older than 30 days
502The voiceover could not be made (nothing charged); the body has its id

Try it now

curl -X POST $VOICE_API_URL/integrations/call-requests \
  -H "Authorization: Bearer $VOICE_API_KEY" -H "Content-Type: application/json" \
  -d '{"external_id":"TEST-1","phone":"01798XXXXXX",
       "context":{"customer_name":"Test Customer","order_id":"TEST-1","total":1450}}'

curl        $VOICE_API_URL/integrations/call-requests/TEST-1 -H "Authorization: Bearer $VOICE_API_KEY"
curl -X DELETE $VOICE_API_URL/integrations/call-requests/TEST-1 -H "Authorization: Bearer $VOICE_API_KEY"

# A voiceover: pick a voice id from the first call, then save the audio
curl        $VOICE_API_URL/integrations/tts/voices -H "Authorization: Bearer $VOICE_API_KEY"
curl -X POST $VOICE_API_URL/integrations/tts -o voiceover.mp3 \
  -H "Authorization: Bearer $VOICE_API_KEY" -H "Content-Type: application/json" \
  -d '{"voice_id":"VOICE_ID","text":"আপনার অর্ডারটি আজ পাঠানো হয়েছে।"}'

What we need from you

  1. The HTTPS URL to POST results to.
  2. 20 real phone numbers straight from your orders table. We handle number formatting, but we need to see your real data first.
  3. Which orders should get a call: all of them, COD only, or orders above a certain value?
  4. What confirmed should do: update the order automatically, or just report it?
  5. (Optional) How your company name should sound. The agent introduces itself with the company name we set up on your account. Tell us only if the spoken Bangla should differ from the written name (for example, "Quantizer" said as "কোয়ান্টাইজার").

What you get from us

  1. An API key for each environment. You can revoke each one separately.
  2. The webhook signing secret.
  3. The base URL.
  4. A dedicated outbound number: the same caller ID every time, so your customers can save it and call back. Tell your support staff which number it is. If someone calls it back, they hear a short recorded message in Bangla saying a staff member will get back to them, and then the call ends. The number never starts a conversation with the bot.
  5. A test assistant that only calls your own phones, so you can try the whole flow before any real customer gets a call.