Skip to content

Commit 304bec5

Browse files
Devon-WhiteDevon-White
authored
Merge pull request #345 from signalwire/worktree-swml-transcribe-docs
Document transcribe / transcribe_stop background call transcription
2 parents ffedcee + d131d8f commit 304bec5

26 files changed

Lines changed: 760 additions & 55 deletions

File tree

‎fern/apis/signalwire-rest/openapi.yaml‎

Lines changed: 310 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -344,6 +344,8 @@ paths:
344344
| `calling.detect.stop` | Stop active detector |
345345
| `calling.tap` | Tap call audio to an RTP or WebSocket endpoint |
346346
| `calling.tap.stop` | Stop active tap |
347+
| `calling.transcribe` | Start background transcription of a call |
348+
| `calling.transcribe.stop` | Stop active transcription |
347349
| `calling.stream` | Stream call audio to a WebSocket endpoint |
348350
| `calling.stream.stop` | Stop active stream |
349351
| `calling.denoise` | Start noise reduction on a call |
@@ -690,6 +692,23 @@ paths:
690692
id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
691693
params:
692694
control_id: tap-control-1
695+
calling.transcribe:
696+
summary: calling.transcribe
697+
description: Start background transcription on an active call
698+
value:
699+
command: calling.transcribe
700+
id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
701+
params:
702+
control_id: transcribe-control-1
703+
status_url: https://example.com/transcribe-status
704+
calling.transcribe.stop:
705+
summary: calling.transcribe.stop
706+
description: Stop an active transcription operation
707+
value:
708+
command: calling.transcribe.stop
709+
id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
710+
params:
711+
control_id: transcribe-control-1
693712
calling.stream:
694713
summary: calling.stream
695714
description: Start streaming call audio to a WebSocket endpoint
@@ -16904,6 +16923,8 @@ components:
1690416923
- $ref: '#/components/schemas/Calling.CallDetectStopRequest'
1690516924
- $ref: '#/components/schemas/Calling.CallTapRequest'
1690616925
- $ref: '#/components/schemas/Calling.CallTapStopRequest'
16926+
- $ref: '#/components/schemas/Calling.CallTranscribeRequest'
16927+
- $ref: '#/components/schemas/Calling.CallTranscribeStopRequest'
1690716928
- $ref: '#/components/schemas/Calling.CallStreamRequest'
1690816929
- $ref: '#/components/schemas/Calling.CallStreamStopRequest'
1690916930
- $ref: '#/components/schemas/Calling.CallDenoiseRequest'
@@ -16942,6 +16963,8 @@ components:
1694216963
calling.detect.stop: '#/components/schemas/Calling.CallDetectStopRequest'
1694316964
calling.tap: '#/components/schemas/Calling.CallTapRequest'
1694416965
calling.tap.stop: '#/components/schemas/Calling.CallTapStopRequest'
16966+
calling.transcribe: '#/components/schemas/Calling.CallTranscribeRequest'
16967+
calling.transcribe.stop: '#/components/schemas/Calling.CallTranscribeStopRequest'
1694516968
calling.stream: '#/components/schemas/Calling.CallStreamRequest'
1694616969
calling.stream.stop: '#/components/schemas/Calling.CallStreamStopRequest'
1694716970
calling.denoise: '#/components/schemas/Calling.CallDenoiseRequest'
@@ -17242,6 +17265,91 @@ components:
1724217265
unevaluatedProperties:
1724317266
not: {}
1724417267
title: calling.tap.stop
17268+
Calling.CallTranscribeRequest:
17269+
type: object
17270+
required:
17271+
- id
17272+
- command
17273+
- params
17274+
properties:
17275+
id:
17276+
allOf:
17277+
- $ref: '#/components/schemas/uuid'
17278+
description: The unique identifying ID of a existing call.
17279+
examples:
17280+
- 3fa85f64-5717-4562-b3fc-2c963f66afa6
17281+
command:
17282+
type: string
17283+
enum:
17284+
- calling.transcribe
17285+
description: The `calling.transcribe` command starts transcribing an active call in the background.
17286+
examples:
17287+
- calling.transcribe
17288+
params:
17289+
type: object
17290+
properties:
17291+
control_id:
17292+
type: string
17293+
description: Unique identifier for this transcription operation, used to control it later.
17294+
examples:
17295+
- transcribe-control-1
17296+
status_url:
17297+
type: string
17298+
format: uri
17299+
description: An HTTP or HTTPS URL that receives the status callback when the transcription finishes.
17300+
examples:
17301+
- https://example.com/transcribe-status
17302+
required:
17303+
- control_id
17304+
unevaluatedProperties:
17305+
not: {}
17306+
description: An object of parameters that will be utilized by the active command.
17307+
unevaluatedProperties:
17308+
not: {}
17309+
description: |-
17310+
Transcribe the entire call in the background.
17311+
17312+
The transcription covers the whole call and completes when the call ends. For real-time
17313+
transcription, use `calling.live_transcribe`. Only one transcription can be active on a call
17314+
at a time; starting another while one is running returns a `409` conflict. Stop it with
17315+
`calling.transcribe.stop` using the same `control_id`.
17316+
title: calling.transcribe
17317+
Calling.CallTranscribeStopRequest:
17318+
type: object
17319+
required:
17320+
- id
17321+
- command
17322+
- params
17323+
properties:
17324+
id:
17325+
allOf:
17326+
- $ref: '#/components/schemas/uuid'
17327+
description: The unique identifying ID of a existing call.
17328+
examples:
17329+
- 3fa85f64-5717-4562-b3fc-2c963f66afa6
17330+
command:
17331+
type: string
17332+
enum:
17333+
- calling.transcribe.stop
17334+
description: The `calling.transcribe.stop` command stops an active transcription operation.
17335+
examples:
17336+
- calling.transcribe.stop
17337+
params:
17338+
type: object
17339+
properties:
17340+
control_id:
17341+
type: string
17342+
description: The control ID of the transcription operation to stop.
17343+
examples:
17344+
- transcribe-control-1
17345+
required:
17346+
- control_id
17347+
unevaluatedProperties:
17348+
not: {}
17349+
description: An object of parameters that will be utilized by the active command.
17350+
unevaluatedProperties:
17351+
not: {}
17352+
title: calling.transcribe.stop
1724517353
Calling.CallTransferRequest:
1724617354
type: object
1724717355
required:
@@ -18741,6 +18849,80 @@ components:
1874118849
unevaluatedProperties:
1874218850
not: {}
1874318851
description: WebSocket tap target parameters.
18852+
Calling.TranscribeStatusCallbackPayload:
18853+
type: object
18854+
required:
18855+
- event_type
18856+
- timestamp
18857+
- project_id
18858+
- space_id
18859+
- params
18860+
properties:
18861+
event_type:
18862+
type: string
18863+
enum:
18864+
- calling.transcript.completed
18865+
- calling.transcript.failed
18866+
description: Whether the transcription completed or failed.
18867+
examples:
18868+
- calling.transcript.completed
18869+
timestamp:
18870+
type: number
18871+
description: When the event was sent, as a Unix timestamp in seconds.
18872+
examples:
18873+
- 1777565701.5623918
18874+
project_id:
18875+
allOf:
18876+
- $ref: '#/components/schemas/uuid'
18877+
description: Your project ID.
18878+
examples:
18879+
- 4d0d6f16-5881-4fcc-92a4-02c51a91954d
18880+
space_id:
18881+
allOf:
18882+
- $ref: '#/components/schemas/uuid'
18883+
description: Your Space ID.
18884+
examples:
18885+
- 451ed9ff-e568-4222-8af9-4f9ab7428d09
18886+
params:
18887+
type: object
18888+
properties:
18889+
id:
18890+
allOf:
18891+
- $ref: '#/components/schemas/uuid'
18892+
description: Unique ID for this transcript.
18893+
examples:
18894+
- 0ec5a4da-46b9-4d2c-b724-151add8d4d08
18895+
call_id:
18896+
allOf:
18897+
- $ref: '#/components/schemas/uuid'
18898+
description: ID of the call that was transcribed.
18899+
examples:
18900+
- 2e1e66e5-5d07-413d-9668-55542992eec0
18901+
segment_id:
18902+
allOf:
18903+
- $ref: '#/components/schemas/uuid'
18904+
description: ID of the call leg that was transcribed.
18905+
examples:
18906+
- 2e1e66e5-5d07-413d-9668-55542992eec0
18907+
text:
18908+
type: string
18909+
description: The transcribed text of the call. Omitted when there is no transcribed text.
18910+
examples:
18911+
- A long time ago in a galaxy far, far away, Luke, I am your father. Do or do not, there is no try. May the force be with you. These aren't the droids you're looking for. I find your lack of faith disturbing. The force will be with you always.
18912+
required:
18913+
- id
18914+
- call_id
18915+
- segment_id
18916+
unevaluatedProperties:
18917+
not: {}
18918+
description: The transcript.
18919+
unevaluatedProperties:
18920+
not: {}
18921+
description: |-
18922+
Sent to your `status_url` when the call's transcription is ready.
18923+
`calling.transcript.completed` includes the transcribed text;
18924+
`calling.transcript.failed` means the call could not be transcribed.
18925+
title: Transcript status callback
1874418926
Calling.TtsGender:
1874518927
type: string
1874618928
enum:
@@ -36661,6 +36843,8 @@ components:
3666136843
- $ref: '#/components/schemas/SWML.Calling.StopTap'
3666236844
- $ref: '#/components/schemas/SWML.Calling.Switch'
3666336845
- $ref: '#/components/schemas/SWML.Calling.Tap'
36846+
- $ref: '#/components/schemas/SWML.Calling.Transcribe'
36847+
- $ref: '#/components/schemas/SWML.Calling.TranscribeStop'
3666436848
- $ref: '#/components/schemas/SWML.Calling.Transfer'
3666536849
- $ref: '#/components/schemas/SWML.Calling.Unset'
3666636850
- $ref: '#/components/schemas/SWML.Calling.Pay'
@@ -37568,6 +37752,32 @@ components:
3756837752
unevaluatedProperties:
3756937753
not: {}
3757037754
title: toggle_functions Action
37755+
SWML.Calling.Transcribe:
37756+
type: object
37757+
required:
37758+
- transcribe
37759+
properties:
37760+
transcribe:
37761+
type: object
37762+
properties:
37763+
status_url:
37764+
type: string
37765+
format: uri
37766+
description: An http or https URL that receives the status callback when the transcription finishes
37767+
examples:
37768+
- https://example.com/transcribe-status
37769+
unevaluatedProperties:
37770+
not: {}
37771+
description: |-
37772+
Transcribe the entire call in the background.
37773+
Execution continues to the next instruction while the call proceeds; the transcription covers the whole call and completes when the call ends.
37774+
For real-time transcription delivered as the call happens, use `live_transcribe` instead.
37775+
Only one transcription can be active on a call at a time.
37776+
To stop it, use the `transcribe_stop` method.
37777+
title: transcribe
37778+
unevaluatedProperties:
37779+
not: {}
37780+
title: transcribe Method
3757137781
SWML.Calling.TranscribeAction:
3757237782
anyOf:
3757337783
- $ref: '#/components/schemas/SWML.Calling.TranscribeStartAction'
@@ -37672,6 +37882,24 @@ components:
3767237882
unevaluatedProperties:
3767337883
not: {}
3767437884
title: TranscribeStartAction object
37885+
SWML.Calling.TranscribeStop:
37886+
type: object
37887+
required:
37888+
- transcribe_stop
37889+
properties:
37890+
transcribe_stop:
37891+
type: object
37892+
unevaluatedProperties:
37893+
not: {}
37894+
description: |-
37895+
Stop the transcription currently running on the call, started with `transcribe`.
37896+
No parameters are required.
37897+
title: transcribe_stop
37898+
examples:
37899+
- {}
37900+
unevaluatedProperties:
37901+
not: {}
37902+
title: transcribe_stop Method
3767537903
SWML.Calling.TranscribeSummarizeAction:
3767637904
type: object
3767737905
required:
@@ -45912,6 +46140,88 @@ servers:
4591246140
default: '{Your_Space_Name}'
4591346141
description: Your SignalWire Space name
4591446142
webhooks:
46143+
transcribeStatusCallback:
46144+
post:
46145+
operationId: transcribe_status_callback
46146+
summary: Transcript status callback
46147+
requestBody:
46148+
required: true
46149+
content:
46150+
application/json:
46151+
schema:
46152+
type: object
46153+
properties:
46154+
event_type:
46155+
type: string
46156+
enum:
46157+
- calling.transcript.completed
46158+
- calling.transcript.failed
46159+
description: Whether the transcription completed or failed.
46160+
example: calling.transcript.completed
46161+
timestamp:
46162+
type: number
46163+
description: When the event was sent, as a Unix timestamp in seconds.
46164+
example: 1777565701.5623918
46165+
project_id:
46166+
type: string
46167+
format: uuid
46168+
description: Your project ID.
46169+
example: 4d0d6f16-5881-4fcc-92a4-02c51a91954d
46170+
space_id:
46171+
type: string
46172+
format: uuid
46173+
description: Your Space ID.
46174+
example: 451ed9ff-e568-4222-8af9-4f9ab7428d09
46175+
params:
46176+
type: object
46177+
properties:
46178+
id:
46179+
type: string
46180+
format: uuid
46181+
description: Unique ID for this transcript.
46182+
example: 0ec5a4da-46b9-4d2c-b724-151add8d4d08
46183+
call_id:
46184+
type: string
46185+
format: uuid
46186+
description: ID of the call that was transcribed.
46187+
example: 2e1e66e5-5d07-413d-9668-55542992eec0
46188+
segment_id:
46189+
type: string
46190+
format: uuid
46191+
description: ID of the call leg that was transcribed.
46192+
example: 2e1e66e5-5d07-413d-9668-55542992eec0
46193+
text:
46194+
type: string
46195+
description: The transcribed text of the call. Omitted when there is no transcribed text.
46196+
example: A long time ago in a galaxy far, far away, Luke, I am your father. Do or do not, there is no try. May the force be with you. These aren't the droids you're looking for. I find your lack of faith disturbing. The force will be with you always.
46197+
required:
46198+
- id
46199+
- call_id
46200+
- segment_id
46201+
unevaluatedProperties:
46202+
not: {}
46203+
description: The transcript.
46204+
required:
46205+
- event_type
46206+
- timestamp
46207+
- project_id
46208+
- space_id
46209+
- params
46210+
unevaluatedProperties:
46211+
not: {}
46212+
description: |-
46213+
Sent to your `status_url` when the call's transcription is ready.
46214+
`calling.transcript.completed` includes the transcribed text;
46215+
`calling.transcript.failed` means the call could not be transcribed.
46216+
responses:
46217+
'200':
46218+
description: Webhook received
46219+
description: |-
46220+
Sent to your `status_url` when the call's transcription is ready.
46221+
`calling.transcript.completed` includes the transcribed text;
46222+
`calling.transcript.failed` means the call could not be transcribed.
46223+
tags:
46224+
- Calls
4591546225
messageStatusCallback:
4591646226
post:
4591746227
operationId: message_status_callback

‎fern/products/apis/apis.yml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,11 @@ navigation:
7272
- section: Calling
7373
skip-slug: true
7474
contents:
75-
- calls
75+
- calls:
76+
- section: Webhooks
77+
slug: webhooks
78+
contents:
79+
- subpackage_calls.transcribe_status_callback
7680
- queues
7781
- queueMembers
7882
- recordings

0 commit comments

Comments
 (0)