Skip to main content
VARTA
Use cases

How do I wire a voice agent to confirm COD orders, share status, and reschedule delivery?

You trigger the call from your own store's order events, not from anything VARTA subscribes to: a webhook lands on your backend, your backend decides which agent and which script the moment calls for, and your backend calls POST /v1/calls. There is no Shopify connector -- Shopify's orders/create webhook is used below as one concrete example of the trigger, but the pattern is the same for any storefront that can call a webhook on an event.

The three moments this covers

  • COD confirmation -- right after an order is placed, before it ships, confirm the customer still wants a cash-on-delivery order and hasn't been targeted by a fraud wave of fake orders in their name.
  • Order status -- a customer-initiated check, or a proactive "your order shipped" call.
  • Delivery rescheduling -- the carrier reports a failed or upcoming attempt, and the agent asks the customer to pick a new window.

Each is a different agent (a different call flow you author in the studio), triggered by a different store event, but they all go through the same integration shape.

The call sequence

  1. Your backend receives the store's webhook (Shopify's orders/create, or your platform's equivalent) and validates its signature.
  2. It maps the order to an agent and builds the call context.
  3. It calls POST /v1/calls, with the Idempotency-Key derived from the order id so a webhook retry -- which every store's webhook delivery will eventually do -- can't dial the same customer twice for the same order event.
curl -X POST "$VARTA_BASE_URL/calls" \
  -H "Authorization: Bearer $VARTA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cod-confirm-ORD-88213" \
  -d '{
    "agent_id": "ag_412",
    "to": "+9198xxxxxxx",
    "customer_name": "Rahul",
    "context": {"order_id": "ORD-88213", "cod_amount": 2350, "sku_summary": "1x running shoes, size 9"}
  }'

Agent ids are numeric and studio-assigned. ag_412 above is the shape the API actually issues: /v1 strips the ag_ prefix and parses the rest as an integer (backend/app/api/v1/_ids.py:56-61), so an author-chosen slug like ag_cod_confirm is rejected as malformed before any lookup happens. Use the id the studio gave your agent.

That request only prepares the call by default -- add "dial": true (and a trunk_id if your tenant has zero or more than one trunk: zero leaves nothing to default to, more than one leaves the choice ambiguous) once you want it to actually ring. See Place a call for the full request/response shape and why the Idempotency-Key matters here specifically: a duplicate COD-confirmation call to the same customer about the same order is not a harmless retry, it is a second phone call about money.

  1. Poll GET /v1/calls/{call_id} for status, or listen for whatever your deployment uses to notify you the call ended.
  2. Once the call is done, read back what the customer said -- confirmed, wants a different delivery window, wants to cancel -- from the session it ran on. The order status and reschedule flows follow the identical POST /v1/calls → poll → read-back shape, with a different agent_id and a context shaped for that script (a reschedule agent needs the carrier's offered windows in context, for instance).

What you still have to build

  • The webhook receiver itself -- endpoint, signature verification, retry handling, and the order → agent/context mapping. VARTA has no knowledge of your storefront's event shape.
  • Fraud or COD-risk logic upstream of the call -- deciding which orders warrant a confirmation call is a business rule you own, not something POST /v1/calls decides.
  • Reading the outcome back into your OMS -- VARTA records what happened on the call; writing "customer confirmed" or "customer wants Tuesday" back into your order management system is your integration to write.
  • Carrier-side rescheduling -- the agent captures the customer's preferred window; actually moving the delivery slot with your logistics provider is a separate API call you make after the fact.
  • Consent and do-not-call handling -- a customer who has opted out of calls for this order or account needs to be excluded before you ever reach POST /v1/calls.