Skip to Content

Send Call

POST/api/v1/webhooks/calls
Forwards the details of a PBX call to ThinkVoice for analysis. Uses the X-Api-Key and X-Api-Secret headers instead of a Bearer token.

When a call ends, send its details to this endpoint. ThinkVoice saves the call and queues it for analysis; when the analysis completes, the Call Analysis Completed webhook is sent to you if configured.

Headers

FieldTypeRequiredDescription
X-Api-Keystring (GUID)YesAPI key provided by our team for your integration.
X-Api-Secretstring (GUID)YesAPI secret specific to your company.
Content-TypestringYesapplication/json

Request Body

{ "id": "20260410-143512-00042", "startTime": "2026-04-10T11:35:12Z", "answerTime": "2026-04-10T11:35:20Z", "endTime": "2026-04-10T11:41:47Z", "source": "02121234567", "callerName": "Ahmet Yılmaz", "destination": "08501234567", "externalSupportPersonnelId": "1042", "supportPersonnelName": "Ayşe Yılmaz", "duration": "00:06:35", "talkDuration": 387, "queueWaitSeconds": 12, "queue": "musteri-hizmetleri", "queueName": "Müşteri Hizmetleri", "missed": false, "result": 1, "hangupDirection": 0, "direction": 0, "recordUrl": "https://santral.firma.com/kayitlar/20260410-143512-00042.wav" }

Parameters

FieldTypeRequiredDescription
idstringYesUnique ID of the call in your system. You will use this value when uploading the recording later.
startTimedatetime (UTC)YesMoment the call started. Must be UTC and end with Z. E.g. 2026-04-10T11:35:12Z
answerTimedatetime (UTC)YesMoment the call was answered. Must be UTC and end with Z. Cannot be later than endTime.
endTimedatetime (UTC)YesMoment the call ended. Must be UTC and end with Z. Cannot be earlier than startTime or answerTime.
sourcestringNoCalling party (number or extension).
callerNamestringNoName of the calling party.
destinationstringNoCalled party (number or extension).
externalSupportPersonnelIdstringNoID, in your system, of the agent who handled the call.
supportPersonnelNamestringNoName of the agent who handled the call.
durationstringNoTotal call duration (as text).
talkDurationintNoTalk time (seconds).
queueWaitSecondsintNoTime spent waiting in the queue (seconds).
queuestringNoQueue the call landed in. If empty or "-", the call is written to the undefined queue (UNDEFINED).
queueNamestringNoDisplay name of the queue. If omitted, the queue value is used.
missedboolNotrue if the call was missed.
resultintNoCall result. 1 = Answered, 3 = Busy, 4 = Not Answered, 5 = Missed, 6 = Failed, 7 = Invalid Number.
hangupDirectionintNoWho ended the call. -1 = Unknown (default), 0 = Customer, 1 = Customer service, 2 = System.
directionintNoCall direction. 0 = Inbound, 1 = Outbound.
recordUrlstringNoURL where the recording can be downloaded. If you prefer to send the recording as a file, leave this field empty and use the Upload Recording endpoint.

startTime, answerTime and endTime must be in UTC. Dates without time zone information (2026-04-10T14:35:12) or with a local offset (+03:00) are rejected with 400. Convert your local time to UTC before sending.

You can deliver the recording in two ways: by providing a URL in the recordUrl field, or by sending the file directly with the Upload Recording endpoint. Agree with our team during the integration on which one will be used for your account.

Example cURL

curl --request POST 'https://public-api.thinkvoice.ai/api/v1/webhooks/calls' \
--header 'X-Api-Key: <API_KEY>' \
--header 'X-Api-Secret: <API_SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "id": "20260410-143512-00042",
  "startTime": "2026-04-10T11:35:12Z",
  "answerTime": "2026-04-10T11:35:20Z",
  "endTime": "2026-04-10T11:41:47Z",
  "queue": "musteri-hizmetleri",
  "result": 1,
  "direction": 0,
  "recordUrl": "https://santral.firma.com/kayitlar/20260410-143512-00042.wav"
}'

Responses

200Success
{ "success": true, "message": "019e925a-5f79-7778-b0be-a45a146cf828 successfully processed" }

If a problem occurs during processing, the HTTP status may still be 200, but the success field will be false and the reason will be given in message. To consider a submission successful, check the success field, not just the HTTP status.

400Date validation failed
{ "success": false, "message": "StartTime, EndTime and AnswerTime must be UTC." }
401Invalid API key / secret
{ "success": false, "message": "Unregistered Tenant." }
MessageHTTPDescription
StartTime, EndTime and AnswerTime must be UTC.400One of the dates was not sent in UTC (Z).
EndTime cannot be earlier than StartTime.400endTime is before startTime.
EndTime cannot be earlier than AnswerTime.400endTime is before answerTime.
Unregistered Tenant.401X-Api-Key / X-Api-Secret is missing, invalid or disabled.
An error occurred while processing the call data.500Unexpected error. Try again.
Last updated: