Connect TaskVox to your CRM, website or app

1 Create your API key

1. Type a name for the key, for example “CRM production”.
2. Click + Generate Key.
3. Copy the key straight away — it is shown only once. It starts with tvx_.

Store it on your server or in your no-code tool’s secret settings. Never put it in website JavaScript or a mobile app: anyone who sees it can place calls on your credits. You can Revoke a key on the same page at any time.

2 Copy the agent ID

Every call is made by one of your agents. Copy the value in the ID column for the agent that should call (for example sales-agent-01). You can also list them with the API:

curl https://taskvox.in/api/agents \
  -H "X-API-Key: tvx_your_key_here"

3 Start calls with the API

Send the agent ID and the numbers. Add "autoStart": true so calling begins immediately — without it the campaign is only created and nothing is dialled.

curl -X POST https://taskvox.in/api/campaigns \
  -H "X-API-Key: tvx_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lead-48213" \
  -d '{
    "name": "Website lead 48213",
    "agentId": "sales-agent-01",
    "numbers": [{ "number": "9198XXXXXXXX", "variables": { "name": "Rahul" } }],
    "autoStart": true
  }'

• numbers can be plain numbers ("9198XXXXXXXX") or objects with variables — such as the lead’s name — that your agent’s script can use.
• Idempotency-Key (optional, recommended): use your lead ID, so if your system retries the request the person is not called twice.
• The response includes the campaign id and "started": true. If it says "started": false, read startError — see Troubleshooting.
• Calls go out only between 8 am and 8 pm IST, and numbers on your do-not-call list are skipped. A campaign created outside those hours is not started and does not start by itself later — queue such leads and start the campaign after 8 am with POST /api/campaigns/{id}/start.

4 Add your webhook

1. Name — anything, for example “CRM integration”.
2. Endpoint URL — paste the public address (use https://) where you want results delivered (your server route, or the URL your Zapier / Make step gives you).
3. Events — tick what you need: call.completed (ticked by default), call.failed, campaign.started, campaign.completed.
4. Click Create Webhook and copy the secret that appears — you need it to check that deliveries really come from TaskVox.
5. Click Test next to the webhook. TaskVox sends a sample event ("event": "test") to your URL and shows whether it got through.

5 Receive the result and update your CRM

Each delivery is a JSON POST like this:

{
  "event": "call.completed",
  "timestamp": "2026-10-09T09:57:09.405Z",
  "data": {
    "call_id": "564a5b3e-95db-4e2c-8f73-5a8c35dcf39d",
    "agent_id": "sales-agent-01",
    "campaign_id": "a1b2c3d4",
    "from": "07447154662",
    "to": "9198XXXXXXXX",
    "duration_seconds": 75,
    "turns": 6,
    "status": "answered",
    "transcript": [ { "role": "assistant", "text": "Namaste! …" }, { "role": "user", "text": "…" } ],
    "lead": {
      "label": "hot",
      "score": 82,
      "summary": "Interested in a 2 BHK, budget ₹80 lakh, wants a site visit on Saturday.",
      "collected_fields": { "budget": "₹80 lakh", "timeline": "2–3 months" }
    },
    "recording_url": "https://taskvox.in/api/calls/564a5b3e-95db-4e2c-8f73-5a8c35dcf39d/recording"
  }
}

Before trusting it, check the X-TaskVox-Signature header: it is an HMAC-SHA256 of the raw request body, made with your webhook secret. Then reply 200 quickly and update the CRM:

// Node.js + Express
const crypto = require('crypto');
app.post('/taskvox/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto.createHmac('sha256', process.env.TASKVOX_WEBHOOK_SECRET)
    .update(req.body).digest('hex');
  const got = req.get('X-TaskVox-Signature') || '';
  if (got.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
    return res.status(401).send('bad signature');
  }
  res.sendStatus(200);                       // reply first…
  const evt = JSON.parse(req.body);          // …then do the work
  if (evt.event === 'call.completed') {
    // find the lead by evt.data.to or by your own ID, save the transcript,
    // and create a follow-up task
  }
});

lead carries the lead label (hot, warm, cold or not_a_lead), score, summary and the answers collected; recording_url downloads the recording with your API key. Its values are null when there was no conversation to analyse, and recording_url is null when no recording exists. The same labels and summaries are on the Leads page in your dashboard, where you can also download them as CSV.

6 Go-live checklist

• The API key lives only on your server or in your no-code tool.
• Your webhook replies 200 within a few seconds. A failed delivery is retried after about 1, 5 and 15 minutes; after that it is dropped.
• You ignore repeats by the X-TaskVox-Delivery header or data.call_id.
• If you must never miss a result, you also check GET /api/calls on a schedule.
• You queue leads that arrive after 8 pm and start them after 8 am.