SparkTG

Moving to API v2 Documentation

Moving to API v2

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

What is sent
Username + password (v1):A login password, on every request
API token (v2):A signed token; no password ever leaves your admin's hands
If it leaks
Username + password (v1):Works until the password is changed, and the same password may open the dashboard too
API token (v2):Revoke that one token instantly on the API Access Tokens screen; dashboard logins are unaffected
Scope
Username + password (v1):Whatever that user can access
API token (v2):Exactly one service, fixed in the token
Lifetime
Username + password (v1):No expiry
API token (v2):Expires after one year; rotate by generating a new token
Who can create it
Username + password (v1):Anyone holding the password
API token (v2):Only a service admin, after a one-time password (OTP) check
Stability
Username + password (v1):Breaks when someone changes the password
API token (v2):Not tied to any login password
Visibility
Username + password (v1):—
API token (v2):Every request is recorded against the token's service

Generate an API token

  1. 1Open Admin → Settings → API Access Tokens in the SparkTG dashboard.
  2. 2Under Generate a new token, choose where to receive the one-time password (SMS, WhatsApp or Email) and request it.
  3. 3Enter the OTP, optionally add a label (for example, the name of your integration) and generate the token.
  4. 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

Base URL
v1 (today):https://telephonycloud.co.in/api/v1
v2:https://telephonycloud.co.in/api/v2
Authentication
v1 (today):Authorization: Basic <username:password>
v2:Authorization: Bearer <YOUR_TOKEN>
Service id (svc-id / service-id)
v1 (today):Selects the service.
v2:Optional. The service always comes from the token. If you send it, it must match the token's service, otherwise HTTP 403.
Agent for an action
v1 (today):Taken from the parameters you send.
v2:Same. If you send no agent-sip, agent-id or agent-number, the action falls back to the admin who generated the token, so send the agent's agent-sip, agent-id or agent-number.
Remove scheduled calls
v1 (today):GET or POST
v2:DELETE only, parameters in the query string
Send WhatsApp message
v1 (today):Sent as the user's agent
v2:Optional agent-id query parameter selects the sending agent
List services
v1 (today):All services of the user
v2:Only the token's service

Successful responses and endpoint-specific errors are the same as in v1. Every v2 request is recorded for API usage billing.

Examples

Username + password (v1)
curl -u '<username>:<password>' \
  'https://telephonycloud.co.in/api/v1/calls?service-id=<SERVICE_ID>&number=9XXXXXXXXX&agent-id=<AGENT_ID>'
API token (v2)
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.

HTTP 401The Authorization header is missing or malformed, or the token has expired.
{"status":"error","code":401,"message":"invalid or missing JWT"}
HTTP 401The token was revoked on the API Access Tokens screen.
{"status":"error","code":401,"message":"token revoked or unknown"}
HTTP 403The service the token belongs to is not active.
{"status":"error","code":403,"message":"service inactive (svcId=<id>)"}
HTTP 403A svc-id or service-id parameter was sent with a different service 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.