Hoppa till huvudinnehållet

Lokalt REST-API

AI Softphone har ett REST-API för CTI-integration: ett program på samma dator kan ringa och styra samtal, läsa kontakter, samtalshistorik och SIP-konton, och bevaka pågående samtal. Inget SDK, ingen mellanhand i molnet och ingen lyssnare som exponeras mot nätverket. Begäranden och svar är JSON, så curl eller vilken HTTP-klient som helst räcker.

API:et är av efter installationen; ingenting lyssnar förrän du slår på det. Därefter lyssnar det bara på loopback-gränssnittet — ett litet webbgränssnitt som bara svarar den här datorn — och kan inte nås från kontorsnätverket, ett VPN eller en annan dator.

Använd API:et när ditt program behöver data från telefonen eller måste styra ett samtal. Använd webhookar när det måste reagera på samtal medan de pågår, utan att fråga om och om igen. De flesta integrationer använder båda; de är oberoende av varandra.

Slå på det​

Öppna Inställningar → Integration och gå till Lokal styrning.

  1. Slå på Låt andra program på den här datorn styra telefonen. Servern startar direkt.
  2. Behåll standardvärdet för Port, 8377, om inte ett annat program redan använder den.
  3. Ange eventuellt en Nyckel. När den har sparats visar fältet Sparat — skriv för att ersätta det.
  4. Välj under Åtkomst vilka grupper som ska öppnas: Kontakter, Samtalshistorik, Samtal, och styrningen av dem, Konton, Inställningar, Räknare (mätvärdena). En grupp som är av filtreras inte utan tillhandahålls inte alls.
  5. Prova det: curl http://127.0.0.1:8377/accounts. Är svaret JSON fungerar API:et.

Ingen separat tjänst installeras och ingen omstart behövs. Den del av programmet som gör detta kan stängas av under Moduler (Integration).

API:ets egen sida​

Öppna API:ets egen sida öppnar http://127.0.0.1:8377 i en webbläsare. Adressen svarar med en lista över allt den tillhandahåller, på engelska; adresserna som läser något är länkar du kan följa.

Åtkomst och nyckeln​

Vad ett program får göra beror på om det ändrar sparade data, inte på om det läser:

  • Utan nyckel får vilket program som helst på datorn läsa allt i de öppnade grupperna och styra samtal: ringa, svara, lägga på, parkera, återuppta, koppla vidare och skicka DTMF.
  • Med nyckeln i huvudet Authorization får det också använda slutpunkterna som ändrar det som är sparat. Utan nyckeln visas inte de slutpunkterna på API:ets egen sida, och de svarar 401. Är ingen nyckel satt alls kan ingenting ändra det som är sparat.

Nyckeln sparas i datorns nyckelring, inte i inställningsfilen, och returneras aldrig av /settings.

försiktighet

Utan nyckel kan vilket program som helst som körs på den här datorn styra telefonen, även svara på samtal. På en personlig arbetsstation är det oftast godtagbart. På en delad eller hanterad dator bör du ange en nyckel och behandla den som vilket annat lösenord som helst. Nyckeln skyddar bara de anrop som ändrar sparade data, inte samtalen: vill du hålla andra program borta från samtalen stänger du av Samtal, och styrningen av dem under Åtkomst.

Slutpunkter​

Basadressen är http://127.0.0.1:8377. Slutpunkterna nedan behöver ingen nyckel.

MetodSökvägGör
GET/metricsRäknarna, i Prometheus-format.
GET/uiListan över inspelningar, som en HTML-sida.
GET/ui/recordings/{id}En inspelning med dess utskrift, som en HTML-sida.
GET/ui/recordings/{id}/audioLjudet till sidan ovan.
GET/contactsKontakterna.
GET/contacts/{id}En enskild kontakt.
GET/historySamtalshistoriken, nyast först. Accepterar ?limit=, ?missed=true och ?declined=true.
GET/callsDe pågående samtalen.
POST/callsRinger ett samtal: {"number": "...", "account_id": "..."}.
POST/calls/{id}/answerSvarar på ett samtal.
POST/calls/{id}/hangupLägger på ett samtal.
POST/calls/{id}/holdParkerar ett samtal.
POST/calls/{id}/resumeÅterupptar det.
POST/calls/{id}/dtmfSkickar toner: {"digits": "..."}.
POST/calls/{id}/transferKopplar vidare samtalet: {"target": "..."}.
GET/accountsSIP-kontona och deras registreringstillstånd. Aldrig ett lösenord.
GET/settingsHela konfigurationen, utan hemligheterna.
GET/taxonomyKategorier, etiketter och signaler, med sina koder.

Slutpunkter som kräver nyckeln​

De ändrar det som är sparat, så varje begäran måste bära nyckeln i huvudet Authorization. API:ets egen sida visar dem bara för en begäran som bär den.

MetodSökvägGör
POST/contactsLägger till en kontakt: {"name": "...", "number": "...", "account_id": "..."}; account_id är valfritt.
PUT/contacts/{id}Ersätter en kontakt.
DELETE/contacts/{id}Tar bort en kontakt.
DELETE/history/{id}Glömmer ett samtal i samtalsloggen.
DELETE/historyGlömmer hela samtalsloggen. Det går inte att ångra.
PUT/accounts/{id}Ersätter inställningarna för ett konto. Lösenordet är inte bland dem.
PUT/settingsErsätter inställningarna.

Varje identifierare är ett UUID som utfärdas av telefonen: ett samtals id kommer från /calls eller från svaret på POST /calls, ett kontos id från /accounts.

Fältnamnen är i snake_case och ändelsen anger typen: _id är en referens till ett UUID, _ts är en tidpunkt i Unix-millisekunder (UTC), _s är en längd i sekunder. Detsamma gäller för webhookar; bara /settings har egna namn. I REST-API:et är de här värdena JSON-tal, och en okänd tidpunkt är null.

Exempel: ringa ett samtal​

POST /calls ringer ett utgående samtal. Innehållet är JSON med number som ska ringas och eventuellt account_id för kontot det ska ringas från:

curl --location 'http://127.0.0.1:8377/calls' \
--header 'Content-Type: application/json' \
--data '{
"number": "1020",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90"
}'

Svaret är det nya samtalets identifierare:

{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
  • number är obligatoriskt. Utan det är svaret 400 {"error":"a call needs a number"} och ingenting rings.
  • Numret kompletteras på det valda kontot på samma sätt som nummerfältet kompletterar det: 1020 skickas som sip:1020@pbx.example.com. POST /calls/{id}/transfer kompletterar sitt target på samma sätt; ett mål som redan har ett schema eller ett @ skickas som det är.
  • account_id är valfritt; hämta det från GET /accounts. Utan det går samtalet ut på kontot som är valt i huvudfönstret.
  • Använd id i /calls/{id}/…: hangup, hold, resume, dtmf och transfer. Webhookarna för det här samtalet har samma id.

Från en webbsida: klicka för att ringa​

En sida som anropar 127.0.0.1 når datorn som webbläsaren körs på — samma dator som telefonen körs på —, så en klicka-för-att-ringa-knapp i ett CRM behöver ingen egen server:

async function dial(number) {
const r = await fetch("http://127.0.0.1:8377/calls", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ number }),
});
if (!r.ok) console.warn("softphone:", (await r.json()).error);
}

Vad svaren innehåller​

Pågående samtal: GET /calls​

Varje samtal har sitt id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts och callstate_ts.

  • state är dialing, ringing-out, ringing-in, active, hold (parkerat av den här telefonen), onhold (parkerat av den andra parten), conference eller ended. När flera gäller vinner conference över hold, och hold över onhold.
  • muted anger om mikrofonen är avstängd i samtalet; att stänga av mikrofonen ändrar inte state.
  • seance_id är samtalet i vidare mening: samtal som hänger ihop genom en vidarekoppling, en konsultation eller en konferens delar det.
  • event_ts är när svaret skapades. Jämför det med callstate_ts för att se hur länge samtalet har varit i sitt tillstånd, utan att förlita dig på din egen klocka.

Konton: GET /accounts​

Varje konto har sitt id (account_id överallt annars), sina inställningar — transport (udp, tcp eller tls), port, registrar, outbound_proxy, expiry_s och andra —, om det är enabled, och sitt state på växeln: registered medan linjen är uppe. Lösenord ingår aldrig.

Samtalshistorik: GET /history​

Nyast först, 100 poster om inte ?limit= säger något annat. ?missed=true returnerar bara missade samtal, ?declined=true bara de samtal som den här telefonen avvisade.

FältBetydelse
idHistorikpostens egen identifierare. Det är inte samtals-id från /calls och från webhookar; seance_id kopplar ihop de två.
outcomeHuvudklassificeringen: answered, missed, declined eller failed.
answeredtrue eller false.
duration_s0 för ett samtal som aldrig kopplades upp.
number, uriDen andra parten, som nummer och som SIP-adress.
nameFrån Kontakter om numret är känt, annars tomt. Matcha på number, inte på detta.
dialedDe slagna siffrorna, för ett utgående samtal; tomt för ett inkommande.
account, account_idLinjen samtalet gick över.
reasonHur det slutade: local-hangup, remote-hangup, cancelled…
answered_byno om en person svarade; annars det som svarade på samtalet.

Kontakter: GET /contacts​

Varje kontakt har sitt id, name, number och linjen den hör till, account_id och account; ett tomt account betyder att kontakten inte är knuten till någon linje.

Inspelningar​

Inspelningar och utskrifter lämnas inte ut som JSON. API:et tillhandahåller dem som HTML-sidor, /ui och /ui/recordings/{id}: länka till de här sidorna från ditt CRM i stället för att flytta runt ljud. Länken öppnas på datorn som har inspelningen, och ljudet lämnar den aldrig.

Taxonomi och inställningar​

Varje post i /taxonomy har en fast code, en title och en description på gränssnittets språk, en kind (category, tag eller red_flag) och, för signaler, en severity. Matcha på code, aldrig på title: titlarna kommer på det språk telefonen är inställd på. En post med retired: true behålls så att äldre samtal fortfarande kan slås upp; den ges inte längre till nya samtal. Läs in taxonomin en gång vid start för att koppla telefonens ord till dina egna fält.

/settings returnerar konfigurationen utom hemligheterna: ljudenheter och volymer, kodekprioritet, utseende och språk, uppstart, genvägar, diagnostiknivån och tillståndet för båda integrationerna — användbart för ett supportverktyg som måste kontrollera en arbetsstation utan skärmdelning. api.disabled visar åtkomstgrupperna som är av och webhooks.silenced händelserna som är av; tomma listor betyder att allt är på. Den innehåller aldrig SIP-lösenordet, API-nyckeln eller webhookens huvudvärde.

Fel​

Varje fel är JSON med en enda nyckel error, avsedd för människor, inte för maskinell tolkning.

StatusInnehållBetydelse
404{"error":"no such endpoint"}Sökvägen finns inte, eller dess åtkomstgrupp är av; båda ger avsiktligt samma svar.
405{"error":"that endpoint does not take this method"}Sökvägen finns, men tar inte den metoden: till exempel POST /settings i stället för PUT.
401{"error":"writing needs a token, and none is configured"}En slutpunkt som ändrar det som är sparat, på en telefon där fältet Nyckel är tomt. Fyll i det under Lokal styrning.
401{"error":"this endpoint needs the authorization token"}En slutpunkt som ändrar det som är sparat, utan rätt nyckel.
404{"error":"no contact with that id"}Sökvägen är rätt, identifieraren är det inte.
400{"error":"no call with that id"}Samtalet har slutat, eller har aldrig funnits.
400{"error":"a call needs a number"}POST /calls utan nummer. Ingenting ringdes.
400{"error":"no digits to send"}POST /calls/{id}/dtmf utan siffror.
400{"error":"a transfer needs a target"}POST /calls/{id}/transfer utan mål.
400{"error":"the account this call is on is no longer set up"}Samtalets konto togs bort under samtalet, så målet kan inte kompletteras. Ingenting skickades till växeln.

Avvisade begäranden räknas i api_requests_refused_total, så en integration som misslyckas i det tysta syns i mätvärdena och inte bara i dina egna loggar.

Mätvärden​

GET /metrics returnerar varje räknare i telefonen, var och en med en hjälptext. Samla in dem med Prometheus eller läs dem för hand.

RäknareRäknar
calls_incoming_totalMottagna inkommande samtal.
calls_outgoing_totalRingda utgående samtal.
calls_answered_totalSamtal som besvarades.
calls_missed_totalInkommande samtal som inte besvarades.
calls_declined_totalSamtal som avvisades här eller av andra sidan.
calls_failed_totalSamtal som inte kunde kopplas upp.
registrations_succeeded_totalLyckade SIP-registreringar.
registrations_failed_totalSIP-registreringar som avvisades eller tog för lång tid.
webhooks_delivered_totalWebhookar som mottagaren accepterade.
webhooks_failed_totalWebhookar som avvisades eller inte levererades.
webhooks_dropped_totalWebhookar som kastades eftersom kön var full.
api_requests_totalBegäranden som hanterats av API:et.
api_requests_refused_totalAvvisade begäranden: fel nyckel, grupp av eller okänd sökväg.

Uppdatera en äldre integration​

Tidigare versioner använde namn i camelCase och korta identifierare. accountId heter nu account_id, startedAt heter callstart_ts, durationSeconds heter duration_s, answeredBy heter answered_by, och webhookfältet at heter event_ts. Samtal och konton identifieras bara med UUID: runtimeId och identifierare som call-3 eller account-2 returneras eller accepteras inte längre.

När det inte fungerar​

SymtomVad du ska kontrollera
Anslutning nekad på 127.0.0.1:8377Lokal styrning är av, telefonen körs inte, eller porten har ändrats.
404 {"error":"no such endpoint"} för en sökväg på den här sidanDess åtkomstgrupp är av.
Läsning fungerar, skrivning avvisas med 401Slutpunkterna som ändrar sparade data kräver nyckeln i huvudet Authorization, och fältet Nyckel på telefonen måste fyllas i först.
Kategorititlarna är inte på engelskaTitlarna följer gränssnittets språk. Matcha på code från /taxonomy.
accountId, startedAt eller at saknasIntegrationen skrevs för de tidigare namnen; se ovan.

Vid ett problem med registrering eller med själva samtalet öppnar du Diagnostik.