---
title: "Send Speech with callback URL"
method: GET
path: "/{sub_domain}/api/speech-recognition"
tags: ["Speech-Recognition"]
---

# Send Speech with callback URL

`GET /{sub_domain}/api/speech-recognition`

## Request

- Base URL: `https://api.commpeak.com/pbx`
- URL: `https://api.commpeak.com/pbx/{sub_domain}/api/speech-recognition`
- Auth: API key in header `Authorization`

Search transcribed calls and deliver each result to a callback URL you provide.

**When to use.** Automate delivery of speech recognition results into your own system. Matching calls are acknowledged immediately, and each finished transcription is posted to your callback URL as it becomes ready. To fetch one call's transcription directly instead, use `GET /speech-recognition/{call_id}`.

**Parameters.**

- `callback_url` (required): where each result is delivered.
- `callback_method` (required): `POST` or `PUT`.
- `callback_data` (required): a JSON template containing placeholders (see below).
- `token` (required): authorizes the request. To obtain a token, contact your account manager.
- `min_duration`, `max_duration` (integer): restrict by recording length in seconds.
- `call_status` (string): restrict by call status.
- `from`, `till` (date-time): restrict to calls created within this range.
- `language` (string): restrict by transcription language.
- `phrase` (string): match calls whose transcription contains this phrase.
- `summary` (string): match calls whose summary contains this text.
- `rank_description` (string): match by rank description.
- `rank_min`, `rank_max` (integer): rank range, 0 to 100.
- `limit` (integer): page size, max 50, default 50.
- `offset` (integer): page offset.

**Placeholders for `callback_data`.** Replaced with the call's values before the callback is sent.

Speech:

- `{speech_result}`: transcription text
- `{speech_phrases}`: array of detected phrases
- `{speech_task_state}`: current transcription state
- `{speech_summary}`: text summary of the call
- `{speech_rank}`: call rank, 0 to 100
- `{speech_rank_description}`: text describing the rank

Call:

- `{call_id}`, `{caller_user_id}`, `{caller_username}`
- `{start_at}`, `{end_at}`
- `{agent_callerid_name}`, `{agent_callerid_number}`
- `{call_duration}`, `{call_bill_duration}`

**Returns.** `{ "speechRequestId": "...", "callIds": [ ... ] }` acknowledging the matched calls. The full transcriptions arrive later at your callback URL.

**Note.** Only the token used to submit a call can later retrieve that call's transcription.

## Path parameters

- `sub_domain` string, required: PBX Name (subdomain)

## Query parameters

- `callback_url` string, required: The URL where the callback will be sent.
- `callback_method` 'POST' | 'PUT', required: The HTTP method for the callback request. One of: POST, PUT.
- `callback_data` string, required: The data of the callback response action, JSON with placeholders.
- `token` string, required: Speech recognition token.
- `min_duration` integer, nullable: Minimum recording duration in seconds. Default 1.
- `max_duration` integer, nullable: Maximum recording duration in seconds.
- `call_status` string, nullable: The status of the campaign lead at the end of the call. For example: No Answer.
- `from` string, nullable: Minimum call creation date.
- `till` string, nullable: Maximum call creation date.
- `language` string, nullable: Speech recognition language.
- `phrase` string, nullable: Phrase (text) that the speech recognition must include.
- `summary` string, nullable: Text that the speech recognition summary must include.
- `rank_description` string, nullable: Text that the speech recognition rank description must include.
- `rank_min` integer, nullable: Minimum call rank. Minimum 0, Maximum 100.
- `rank_max` integer, nullable: Maximum call rank. Minimum 0, Maximum 100.
- `limit` integer, nullable: Max amount of speech recognitions to return in the callback. Maximum 50. Default 50.
- `offset` integer, nullable: Specify which row to start retrieving from. Default 0.

## Response `200`

Successful Response

- SpeechCallbackResponse
  - `speech_request_id` string, nullable: Identifier for this callback request, echoed to the callback URL.
  - `callIds` string[], nullable: IDs of the calls that were matched and sent.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/commpeak/apis/commpeak-pbx-api.md) - [All operations](https://skmtc.dev/commpeak/apis/commpeak-pbx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/commpeak/apis/commpeak-pbx-api/revisions/0b1e8c7fd3f6?raw)