Taalk Help Center

API and Developer Access

The Taalk REST API lets your own systems place calls, run campaigns, push contacts, check Do-Not-Call status and pull results. This page is the starting point: where keys live, how to authenticate, limits, errors and a map of every public endpoint.

Before you start

  • You need a paid plan. Free workspaces can read the API docs but can't create keys.
  • Create a key in Developer › Integrations › Taalk API Token (free add-on). See API Keys.
  • Browse and try every endpoint in Developer › API docs.

Base URL and authentication

Base URL https://api.taalk.ai/api
Auth header Authorization: Bearer <TAALK_API_KEY>
Body format JSON, up to 5 MB per request
curl https://api.taalk.ai/api/campaign2s \
  -H "Authorization: Bearer $TAALK_API_KEY"

More than one workspace

If you belong to several workspaces, add db=<workspace ID> to the query string. Without it, the request goes to your default workspace. The workspace ID is the db= value in your console address bar after you switch workspace.

curl "https://api.taalk.ai/api/campaign2s?db=<WORKSPACE_ID>" \
  -H "Authorization: Bearer $TAALK_API_KEY"

Try requests in API docs

Go to Developer › API docs.

  1. Pick an endpoint from the list.
  2. Click Test request. The docs sign you in with a short-lived token for your current workspace, so you don't paste a key.
  3. Fill the parameters and send.
Good to know
Real actions The Live server places real calls and texts. Taalk asks you to confirm before a DELETE and before any request that calls or texts someone.
Docs limits About 120 requests and 20 writes per 10 minutes per user.
force Not allowed from the docs (403).

Limits

Limit Value
Keys per user 15
Rate limit Set per key with Rate limit when you create it (Unlimited by default). Over the limit returns 429.
Page size pageSize defaults to 10. Contact lists allow up to 200 per page.
DNC bulk check 100 numbers per request
Long reports /report and /campaign2s/{id}/contacts/report return 413 with Retry-After: 60 if they take too long. Retry after a minute.

Errors

Errors come back as a plain-text message with the HTTP status.

Status Meaning What to do
400 Bad request. Missing field, invalid date range, missing agent or caller ID, missing complianceAttested Read the message and fix the request
401 Invalid, expired or revoked key, a scoped key used outside its scope, no access to that workspace, or your role can't change this item Check the key, its scopes, db and your role
402 Feature not on your plan, or add-on locked Upgrade or unlock the add-on
403 Your plan doesn't allow API calls or DNC checks, or an action reserved for Taalk Upgrade, or contact support
404 Not found, or the campaign isn't running (pause, resume, cancel) Check the ID
406 Restore not possible (the campaign has a current run, or its last run wasn't canceled) Check campaign state
409 Campaign already running, or caller ID used by another campaign Pause the other campaign or pick another caller ID
413 Report still computing Retry after Retry-After seconds
424 Caller ID group has no numbers Add numbers to the group
428 Auto-recharge is off Turn on auto-recharge before launching
429 Rate limit, or too many campaigns running at once Slow down, or pause another campaign

Endpoint map

All updates use POST (not PATCH). The only PATCH endpoint is the DNC list change.

Calls

Method Endpoint What it does
POST /call Call one contact now. Body: name, phone (E.164), optional from, agent, campaign, retryMethod, params, timeout. 200 queued, 202 campaign is after hours, 406 blocked by calling-hour rules
GET /call/{localId} Call status and summary for third-party tools
GET /calls List calls. Filters: range, tz, agent, campaign, phone, direction, answered, amd, transfer
GET /calls/count Count calls matching the same filters
GET /calls/status Live counts: payload.realtime (waiting, pending, in-progress) and payload.messaging (open threads, texts, emails). Optional campaign
GET /calls/export/csv Download calls as CSV
GET /calls/{id} One call: status, summary, details
GET /calls/{id}/transcript Full transcript
GET /calls/{id}/recording Recording (425 while it's still processing)
GET /calls/{id}/recording/all All recording URLs for a call
DELETE /calls/{id}/recording Delete a recording. Can't be undone
GET /calls/{id}/explain AI explanation of the call
POST /calls/{id}/report Report a problem with a call
POST /calls/{id}/action/sms Text the contact on this call
POST /calls/{id}/action/hangup Hang up a live call

Campaigns and contacts

See API Guide: Campaigns and API Guide: Contacts.

Method Endpoint What it does
GET, POST /campaign2s List or create campaigns
GET, POST, DELETE /campaign2s/{id} Read, update or delete a campaign
POST /campaign2s/{id}/{action} start, pause, resume, cancel, restore
POST /campaign2s/segments Count campaigns per filter
GET /campaign2s/{id}/activities Recent changes to the campaign
GET, POST /campaign2s/{id}/contacts List, or add / update / remove contacts
GET, POST /campaign2s/{id}/contacts/{cid} Read or update one contact
GET /campaign2s/{id}/contacts/{cid}/sessions Calls and messages for one contact
GET /campaign2s/{id}/contacts/report Contact analytics (needs tz)
GET /campaign2s/{id}/contacts/fields Custom Taalk_ fields in use
GET /campaign2s/{id}/contacts/export/csv and /jsonl Export a campaign's contacts
GET /contacts Search contacts across campaigns
GET /contacts/export/csv and /jsonl Export contacts across campaigns
POST /contact_form/{campaignId} Send a lead from a web form into a campaign

Agents, knowledge and plugins

Method Endpoint What it does
GET, POST /agents List or create agents
GET, POST, DELETE /agents/{id} Read, update or delete an agent
POST /agents/{id}/lock Lock or unlock (readonly)
POST /agents/{id}/test Place a test call
POST /agents/wizard Draft an agent with AI
GET, POST /knowledges List or create knowledge
GET, POST, DELETE /knowledges/{id} Read, update or delete knowledge
GET, POST /plugins List or create plugins
GET, POST, DELETE /plugins/{id} Read, update or delete a plugin
GET /plugins/{id}/agents Agents that use a plugin

Compliance

See API Guide: DNC and Calling-Hour Checks.

Method Endpoint What it does
GET /dnc/{phone}, /dnc/{type}/{phone} Check one number
POST /dnc Check up to 100 numbers
PATCH /dnc/{type} Add or remove numbers on your list
POST /check_ftc_rule Calling hours and holiday for a state or area code

Reports and other

Method Endpoint What it does
GET /report Dashboard analytics. range, tz, granularity, agent, campaign, timeline, postcall
POST /monitor/engagement Engagement report by hour, day or week (endsAt, granularity, campaign, tz, comparison)
GET /monitor/engagement/{companyId} Saved engagement reports
GET /count/{type} Count agents, knowledges, plugins and more
GET /chatbot_entry Key and URL to embed the chatbot

The API docs list the engagement report as /api/monitor/engagement. The correct path is /monitor/engagement (full URL https://api.taalk.ai/api/monitor/engagement).

Prefer webhooks to polling

To get results as they happen, send them to your system instead of polling:

Costs

Calls, texts and emails you start through the API cost the same as in the console. See How Billing Works.

Related