Gratis setup bij jaarabonnementen

Nu inschrijven!
Plan een demo

Spraak en transcriptie

Home

> API-referentie >

Eindpunten >

Spraak en transcriptie

API-referentie: Spraak- en transcriptie-endpoints

De spraak- en transcriptie-API’s omvatten browser-/PSTN-bellen via Twilio, verwerking van Twilio-callbacks, geüploade audiodelen van oproepen, realtime OpenAI SDP-oproepen en afzonderlijke transcripties van audiobestanden.

Huidige endpoints

Twilio-oproepen

Deze groep combineert beveiligde medewerker-API-calls, audio-upload met telefoonverificatie, anonieme Twilio-callbacks en OpenAI-transcriptie/realtime overdracht. Beveiligde AnswerPal API-endpoints gebruiken JWT Bearer-authenticatie. De Twilio-callbackroutes zijn anoniem omdat Twilio deze direct aanroept.

  • GET /api/TwilioCalls/voice-token – Bearer JWT
    Genereer een Twilio Voice-toegangstoken voor de huidige medewerker. De optionele query twimlAppSidOverride kan de klant TwiML app SID overschrijven. Response bevat token, region en edge.
  • POST /api/TwilioCalls/initiate-call – Bearer JWT
    Start een uitgaande PSTN-oproep met de Twilio-gegevens van de klant. Vereiste velden in body zijn fromNumber en toNumber, beiden genormaliseerd naar +digits.
  • GET /api/TwilioCalls/call-status – Bearer JWT
    Geeft de definitieve Twilio-oproepstatus terug voor query callSid. De service controleert eerst sub-oproepen en valt anders terug op de status van de hoofdoproep.
  • POST /api/TwilioCalls/voice – Public Twilio-callback
    Geeft TwiML terug voor uitgaande oproepen vanaf een browserapparaat. De callback valideert telefoonnummers, eigenaarschap van medewerker/klant en opslaglimieten voordat <Dial> of <Connect><Stream> TwiML wordt teruggegeven.
  • POST /api/TwilioCalls/{repID}/recordingcallback – Public Twilio-callback
    Ontvangt voltooide Twilio-opnamegegevens, downloadt de MP3 van Twilio, maakt of werkt het telefoon-ticket en ticketbericht bij, en transcribeert indien een OpenAI-sleutel en transcriptiemodel beschikbaar zijn.

Spraaktoken en uitgaande oproep

Voice-token

GET /api/TwilioCalls/voice-token
Authorization: Bearer {token}

200 OK
{
  "token": "twilio-jwt...",
  "region": "ie1",
  "edge": "dublin"
}

Oproep starten

POST /api/TwilioCalls/initiate-call
Authorization: Bearer {token}
Content-Type: application/json

{
  "fromNumber": "+3225550100",
  "toNumber": "+32470000000"
}

Twilio-velden

TwilioCallRequest body

  • fromNumber
    Vereist Twilio-beller-nummer voor door de server geïnitieerde oproepen. Moet genormaliseerd worden naar +digits.
  • toNumber
    Vereist bestemmingsnummer. Moet genormaliseerd worden naar +digits.

Voice callback formulier-velden

  • FromNumber, To, RepID, AccountSid, CallSid
    Kern Twilio-formuliergegevens. AnswerPal valideert het nummerformaat en controleert of de medewerker bij de juiste klant hoort.
  • Record
    Indien waar op het niet-vertalingspad, neemt de teruggegeven TwiML de oproep op en stelt een opname-statuscallback in.
  • Translate
    Indien waar, start de teruggegeven TwiML een <Connect><Stream> met de ingestelde PhoneStreamUrl alvorens te bellen.
  • CallerLanguage, CallerVoice, ReceiverLanguage, ReceiverVoice, ForwardRawAudio
    Optionele vertaal-/streamparameters die als aangepaste parameters aan de Twilio-stream worden doorgegeven.

Recording callback formulier-/queryvelden

  • repID
    Routewaarde. Moet een positieve medewerker-ID zijn en horen bij de juiste klant.
  • customFrom, customTo
    Querywaarden toegevoegd door AnswerPal bij de configuratie van de opnamecallback. Ze identificeren het telefoon-kanaal en het externe nummer.
  • CallSid, AccountSid, RecordingSid, RecordingUrl, RecordingStartTime, RecordingDuration
    Twilio-opnamegegevens gebruikt om klant/kanaal te bepalen, MP3-audio te downloaden en ticket-timing op te bouwen.

Twilio-callbackvoorbeeld

POST /api/TwilioCalls/voice
Content-Type: application/x-www-form-urlencoded

FromNumber=+3225550100
To=+32470000000
RepID=42
Record=true
Translate=false
CallSid=CA...
AccountSid=AC...

Toegang en gedrag

Authenticatie en toegang

  • JWT-routes
    voice-token, initiate-call, call-status, /api/realtime/calls en /api/Transcriptions/file vereisen een medewerker JWT.
  • Telefoonverificatie-route
    /api/AudioChunks/uploadAndFinalize accepteert een medewerker met tickettoegang of een telefoonverificatiecontext. Requests met telefoonverificatie zijn beperkt tot het tokenkanaal.
  • Twilio-callbacks
    /api/TwilioCalls/voice en /api/TwilioCalls/{repID}/recordingcallback zijn anonieme Twilio-callbacks. Zij valideren Twilio Account SID, telefoon-kanaal en eigenaarschap van de medewerker in de applicatielogica.

Gedrag transcriptiemodel

  • OpenAI-sleutel klant
    Transcriptie van audiodelen, opname-callbacktranscriptie, realtime oproepen en bestandstranscriptie vereisen allemaal de geauthenticeerde of gevonden klant OpenAI API-sleutel. Ontbrekende sleutels geven 400 bij directe API-aanroepen of slaan verklarende voorbeeldtekst op in ticket-gestuurde flows.
  • Standaardmodel
    Transcriptie gebruikt het standaard transcriptiemodel van de klant indien geldig, anders het eerst actieve transcriptiemodel van de klant, vervolgens het eerst actieve gedeelde transcriptiemodel. Als er geen bestaat, geeft directe bestandstranscriptie een 400 en slaan ticketflows een diagnostisch voorbeeld op.

Opslaghandhaving

  • Opslaglimietcontrole
    Initiatie uitgaande oproep, Twilio voice callback en audiochunk-upload controleren de opslaglimiet van de klant voordat ze oproepdata aanmaken of opslaan.
GET /api/TwilioCalls/voice-token
Authorization: Bearer {token}

200 OK
{
  "token": "twilio-jwt...",
  "region": "ie1",
  "edge": "dublin"
}
POST /api/TwilioCalls/initiate-call
Authorization: Bearer {token}
Content-Type: application/json

{
  "fromNumber": "+3225550100",
  "toNumber": "+32470000000"
}
POST /api/TwilioCalls/voice
Content-Type: application/x-www-form-urlencoded

FromNumber=+3225550100
To=+32470000000
RepID=42
Record=true
Translate=false
CallSid=CA...
AccountSid=AC...
POST /api/AudioChunks/uploadAndFinalize
Authorization: Bearer {token}
Content-Type: application/json

[
  {
    "ticketID": 123,
    "senderType": "EndUser",
    "timestampMs": 0,
    "base64AudioData": "/////w=="
  }
]

Audio en transcriptie

Spraak- en transcriptie-endpoints verwerken geüploade oproepfragmenten, realtime SDP-oproepen en losse transcriptiebestanden.

  • POST /api/AudioChunks/uploadAndFinalize – Bearer JWT (TicketAccessOrPhoneAuth)
    Accepteer alle audiofragmenten voor een oproepticket in één JSON-array, decodeer mu-law audio, bouw een stereoverslag, sla het op bij het ticket, transcribeer waar mogelijk en maak een systeemticketbericht aan.
  • POST /api/realtime/calls – Bearer JWT
    Stuur een multipart SDP-offer en realtime session JSON door naar OpenAI Realtime calls met de geauthenticeerde klant OpenAI API-sleutel. Geeft het SDP-antwoord terug als application/sdp.
  • POST /api/Transcriptions/file – Bearer JWT
    Upload één audiobestand als multipart form-veld file en ontvang transcriptietekst in { "text": "..." }. Request omvang is beperkt tot 1 GB.

Voorbeeld van audiofragmenten

POST /api/AudioChunks/uploadAndFinalize
Authorization: Bearer {token}
Content-Type: application/json

[
  {
    "ticketID": 123,
    "senderType": "EndUser",
    "timestampMs": 0,
    "base64AudioData": "/////w=="
  }
]

Realtime en bestandstranscriptie

Realtime oproep

POST /api/realtime/calls
Authorization: Bearer {token}
Content-Type: multipart/form-data

sdp:      application/sdp
session:  application/json

Bestandstranscriptie

POST /api/Transcriptions/file
Authorization: Bearer {token}
Content-Type: multipart/form-data

file: call-recording.mp3

200 OK
{ "text": "Transcribed audio text..." }

Velden en gedrag

Requestbody's en formuliervelden

TwilioCallRequest body

  • fromNumber
    Vereist Twilio afzendernummer voor server-geïnitieerde oproepen. Moet normaliseren naar +cijfers.
  • toNumber
    Vereist bestemmingsnummer. Moet normaliseren naar +cijfers.

Voice callback formuliervelden

  • FromNumber, To, RepID, AccountSid, CallSid
    Kern Twilio formulierdata. AnswerPal valideert het nummerformaat en controleert of de medewerker tot de gevonden klant behoort.
  • Record
    Indien waar op het niet-vertaalpad, registreert de geretourneerde TwiML de oproep en stelt een recording status callback in.
  • Translate
    Indien waar, start de geretourneerde TwiML een <Connect><Stream> met de ingestelde PhoneStreamUrl voordat er wordt gebeld.
  • CallerLanguage, CallerVoice, ReceiverLanguage, ReceiverVoice, ForwardRawAudio
    Optionele vertaalt/stream-parameters die als custom parameters aan de Twilio-stream worden meegegeven.

Recording callback form/query velden

  • repID
    Routewaarde. Moet een positief medewerker-ID zijn en tot de gevonden klant behoren.
  • customFrom, customTo
    Querywaarden toegevoegd door AnswerPal tijdens het configureren van de recording callback. Identificeren het telefoonkanaal en het externe nummer.
  • CallSid, AccountSid, RecordingSid, RecordingUrl, RecordingStartTime, RecordingDuration
    Twilio opname metadata gebruikt om klant/kanaal te bepalen, MP3-audio te downloaden en tickettiming op te bouwen.

AudioChunkCreateDTO array items

  • ticketID
    Verplicht positief ticket-ID. Het ticket moet bestaan en bij de geauthenticeerde klant horen. Requests met telefoonauthenticatie moeten overeenkomen met het tokenkanaal.
  • senderType
    Verplichte sprekerlabel. De huidige validator accepteert EndUser, AI of CustomerRep.
  • timestampMs
    Milliseconden sinds het begin van het gesprek. Fragmenten worden gesorteerd op deze waarde voordat de audio wordt gemixt.
  • base64AudioData
    Verplichte base64-gecodeerde mu-law audiobytes. De API decodeert 8 kHz mu-law naar PCM en bouwt stereo output.

RealtimeCallRequest multipart velden

  • sdp
    Verplicht SDP-offerveld. Wordt als application/sdp zonder bestandsnaam naar OpenAI gestuurd.
  • session
    Verplicht realtime session configuratie JSON-veld. Wordt als application/json naar OpenAI gestuurd.

Transcriptiebestand upload

  • file
    Verplicht multipart form-bestand. Lege uploads geven 400 terug. De geauthenticeerde klant moet een OpenAI-sleutel en een actief transcriptiegeschikt model hebben.

Toegang, opslag en modellen

Authenticatie en toegang

  • JWT-routes
    voice-token, initiate-call, call-status, /api/realtime/calls en /api/Transcriptions/file vereisen een medewerker JWT.
  • Telefoonauth-gevoelige route
    /api/AudioChunks/uploadAndFinalize accepteert een tickettoegangsmedewerker of een telefoonauth-context. Telefoonauth-aanvragen zijn beperkt tot het tokenkanaal.
  • Twilio-callbacks
    /api/TwilioCalls/voice en /api/TwilioCalls/{repID}/recordingcallback zijn anonieme Twilio-callbacks. Ze valideren Twilio Account SID, telefoonkanaal en medewerkerseigendom in de applicatielogica.

Transcriptiemodelgedrag

  • Klant OpenAI-sleutel
    Transcriptie van audiofragmenten, opname-callbacktranscriptie, realtime oproepen en bestandstranscriptie vereisen allemaal de geauthenticeerde of gevonden klant OpenAI API-sleutel. Ontbrekende sleutels geven 400 terug bij directe API-aanroepen of slaan een toelichtende previewtekst op in ticketgebaseerde flows.
  • Standaardmodel
    Transcriptie gebruikt het klant standaard transcriptiemodel indien geldig, anders het eerste actieve klant transcriptiemodel, dan het eerste actieve gedeelde transcriptiemodel. Als er geen bestaat, geeft directe bestandstranscriptie 400 terug en slaan ticketflows een diagnostische preview op.

Opslaghandhaving

  • Opslaglimiet controles
    Uitgaande oproepinitiatie, Twilio voice callback en upload van audiofragmenten handhaven de klantopslaglimiet voordat oproepgegevens worden aangemaakt of opgeslagen.

Gerelateerde tokens voor telefoonauthenticatie worden uitgegeven door de Auth API via /api/Auth/phone-login. Telefoontickets, berichten, prompts, acties en bijlagen worden toegelicht op de pagina’s met tickets- en bestandsendpoints.

POST /api/TwilioCalls/voice en POST /api/TwilioCalls/{repID}/recordingcallback zijn anoniem omdat Twilio ze rechtstreeks aanroept. Ze valideren echter nog steeds Account SID, telefoonkanaal en medewerker/klanteigendom.

Audiofragmentpayloads bevatten base64 mu-law audio. AnswerPal decodeert 8 kHz mu-law naar PCM, mixt beller- en AI/medewerker audio tot stereo, slaat de opname op en transcribeert die waar mogelijk.

POST /api/Transcriptions/file geeft { "text": "..." } terug. Dit vereist dat de geauthenticeerde klant over een OpenAI API-sleutel en een actief transcriptiegeschikt model beschikt.

Inhoudsopgave

AnswerPal: AI-gedreven oplossingen voor klantenservice die je ondersteuning en communicatie moeiteloos versterken.

Snelle links

Contact

Voor ondersteunings-, commerciële en partnervragen kunt u mailen naar [email protected]

AnswerPal
Bisschoppenhoflaan 380
2100 Antwerpen
België

+32.36416685

BE 0862.692.858

Sociale media