Call Ingestion
You can forward calls from your PBX or contact center system to ThinkVoice for analysis. The endpoints in this section work from your system to ThinkVoice; to have ThinkVoice notify you when the analysis completes, see the Webhook section.
Endpoints
| Endpoint | Purpose |
|---|---|
POST /api/v1/webhooks/calls | Sends the details of a call. Send Call |
POST /api/v1/webhooks/calls/{callId}/audio | Uploads the recording of a previously sent call as a file. Upload Recording |
POST /api/v1/webhooks/hipcall/calls | Accepts the call_hangup notification from the Hipcall PBX. Hipcall Integration |
Authentication
These endpoints do not use a Bearer token. During the integration, our team provides you with two values:
| Value | Description |
|---|---|
API key | Identifies your integration (PBX/provider). |
API secret | Determines which company (tenant) the data is written to. |
Send these values as headers with every request:
X-Api-Key: <API_KEY>
X-Api-Secret: <API_SECRET>The values are in GUID format. If a missing, invalid or disabled value is sent, the request is rejected with 401. Store these values on the server side only.
For PBXs such as Hipcall that do not support custom headers, the values are passed in the URL query string instead of headers. See the Hipcall Integration page for details.
Response Format
All successful and failed responses share the same simple structure:
{
"success": true,
"message": "019e925a-5f79-7778-b0be-a45a146cf828 successfully processed"
}Rate Limit
The limit for these endpoints is 600 requests per 60 seconds. When exceeded, 429 is returned and the Retry-After header indicates how long to wait, in seconds. If you are doing a bulk transfer, spread your requests so they stay below this limit.
Common Error Codes
| HTTP | Description |
|---|---|
400 | The request body is invalid (missing required field, wrong date format, etc.). The reason is given in the message field. |
401 | X-Api-Key / X-Api-Secret is missing, invalid or disabled. |
404 | The call for which a recording is being uploaded was not found. |
415 | The recording file type is not supported. |
429 | Rate limit exceeded. |
500 | Unexpected error. Try again after a while; if it persists, contact our team. |