Moving to API v2 Documentation
Moving to API v2
Moving to API v2
Moving to API v2
Token-based authentication for your existing integration
Your integration calls the SparkTG API at /api/v1 with a SparkTG username and password sent on every request. API authentication is moving to signed API tokens, available for the same endpoints at /api/v2. The endpoints, parameters and responses stay the same: for most integrations only the base URL and the Authorization header change.
Why move to v2
Generate an API token
- 1Open Admin → Settings → API Access Tokens in the SparkTG dashboard.
- 2Under Generate a new token, choose where to receive the one-time password (SMS, WhatsApp or Email) and request it.
- 3Enter the OTP, optionally add a label (for example, the name of your integration) and generate the token.
- 4Copy the token and store it securely. It is shown only once, and it is valid for one year.
Your service admin generates the token. The same screen lists your tokens and lets you revoke one. Before a token expires, generate a new one and switch your integration to it.
What changes
Successful responses and endpoint-specific errors are the same as in v1. Every v2 request is recorded for API usage billing.
Examples
curl -u '<username>:<password>' \
'https://telephonycloud.co.in/api/v1/calls?service-id=<SERVICE_ID>&number=9XXXXXXXXX&agent-id=<AGENT_ID>'curl -H 'Authorization: Bearer <YOUR_TOKEN>' \
'https://telephonycloud.co.in/api/v2/calls?number=9XXXXXXXXX&agent-id=<AGENT_ID>'Replace <YOUR_TOKEN> with your API token
Token errors
The token is checked before the endpoint runs, so any v2 request can return these.
{"status":"error","code":401,"message":"invalid or missing JWT"}{"status":"error","code":401,"message":"token revoked or unknown"}{"status":"error","code":403,"message":"service inactive (svcId=<id>)"}{"status":"error","code":403,"message":"svc-id does not match token's service"}v2 endpoints
These APIs are available on v2 today. The rest of the SparkTG APIs are moving to v2 soon.
Make a call (v2)
Start an outbound or scheduled call
Click to call (v2)
OTP-verified callback requests
Remove scheduled calls (v2)
Cancel calls that are scheduled
Batch create scheduled calls (v2)
Schedule up to 500 calls in one request
Send a WhatsApp message (v2)
Send a message from your service
Fetch call details in bulk (v2)
Call records for a time range
Login / logout report (v2)
Agent login and logout times
List agents (v2)
Every agent of the token's service
Update an agent (v2)
Log in, log out, breaks and profile changes
Get effective breaks (v2)
Break statuses agents can use, optionally for one agent
CDR report (v2)
Call Detail Records for a time window
Agent performance report (v2)
Per-agent call counts and talk, handle, hold and pickup times
Login / logout raw report (v2)
Login and break timeline, one row per status segment
Login / logout summary report (v2)
Idle, talk, break and logout durations per agent
List services (v2)
The token's service
LeadSquared DID list (v2)
DIDs for the LeadSquared integration
