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.
- Slå på Låt andra program på den här datorn styra telefonen. Servern startar direkt.
- Behåll standardvärdet för Port,
8377, om inte ett annat program redan använder den. - Ange eventuellt en Nyckel. När den har sparats visar fältet Sparat — skriv för att ersätta det.
- 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.
- 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
Authorizationfå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 svarar401. Ä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.
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.
| Metod | Sökväg | Gör |
|---|---|---|
| GET | /metrics | Räknarna, i Prometheus-format. |
| GET | /ui | Listan över inspelningar, som en HTML-sida. |
| GET | /ui/recordings/{id} | En inspelning med dess utskrift, som en HTML-sida. |
| GET | /ui/recordings/{id}/audio | Ljudet till sidan ovan. |
| GET | /contacts | Kontakterna. |
| GET | /contacts/{id} | En enskild kontakt. |
| GET | /history | Samtalshistoriken, nyast först. Accepterar ?limit=, ?missed=true och ?declined=true. |
| GET | /calls | De pågående samtalen. |
| POST | /calls | Ringer ett samtal: {"number": "...", "account_id": "..."}. |
| POST | /calls/{id}/answer | Svarar på ett samtal. |
| POST | /calls/{id}/hangup | Lägger på ett samtal. |
| POST | /calls/{id}/hold | Parkerar ett samtal. |
| POST | /calls/{id}/resume | Återupptar det. |
| POST | /calls/{id}/dtmf | Skickar toner: {"digits": "..."}. |
| POST | /calls/{id}/transfer | Kopplar vidare samtalet: {"target": "..."}. |
| GET | /accounts | SIP-kontona och deras registreringstillstånd. Aldrig ett lösenord. |
| GET | /settings | Hela konfigurationen, utan hemligheterna. |
| GET | /taxonomy | Kategorier, 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.
| Metod | Sökväg | Gör |
|---|---|---|
| POST | /contacts | Lä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 | /history | Glö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 | /settings | Ersä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 svaret400 {"error":"a call needs a number"}och ingenting rings.- Numret kompletteras på det valda kontot på samma sätt som nummerfältet kompletterar det:
1020skickas somsip:1020@pbx.example.com.POST /calls/{id}/transferkompletterar sitttargetpå 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ånGET /accounts. Utan det går samtalet ut på kontot som är valt i huvudfönstret.- Använd
idi/calls/{id}/…:hangup,hold,resume,dtmfochtransfer. Webhookarna för det här samtalet har sammaid.
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ärdialing,ringing-out,ringing-in,active,hold(parkerat av den här telefonen),onhold(parkerat av den andra parten),conferenceellerended. När flera gäller vinnerconferenceöverhold, ochholdöveronhold.mutedanger om mikrofonen är avstängd i samtalet; att stänga av mikrofonen ändrar intestate.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 medcallstate_tsfö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ält | Betydelse |
|---|---|
id | Historikpostens egen identifierare. Det är inte samtals-id från /calls och från webhookar; seance_id kopplar ihop de två. |
outcome | Huvudklassificeringen: answered, missed, declined eller failed. |
answered | true eller false. |
duration_s | 0 för ett samtal som aldrig kopplades upp. |
number, uri | Den andra parten, som nummer och som SIP-adress. |
name | Från Kontakter om numret är känt, annars tomt. Matcha på number, inte på detta. |
dialed | De slagna siffrorna, för ett utgående samtal; tomt för ett inkommande. |
account, account_id | Linjen samtalet gick över. |
reason | Hur det slutade: local-hangup, remote-hangup, cancelled… |
answered_by | no 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.
| Status | Innehåll | Betydelse |
|---|---|---|
| 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äknare | Räknar |
|---|---|
calls_incoming_total | Mottagna inkommande samtal. |
calls_outgoing_total | Ringda utgående samtal. |
calls_answered_total | Samtal som besvarades. |
calls_missed_total | Inkommande samtal som inte besvarades. |
calls_declined_total | Samtal som avvisades här eller av andra sidan. |
calls_failed_total | Samtal som inte kunde kopplas upp. |
registrations_succeeded_total | Lyckade SIP-registreringar. |
registrations_failed_total | SIP-registreringar som avvisades eller tog för lång tid. |
webhooks_delivered_total | Webhookar som mottagaren accepterade. |
webhooks_failed_total | Webhookar som avvisades eller inte levererades. |
webhooks_dropped_total | Webhookar som kastades eftersom kön var full. |
api_requests_total | Begäranden som hanterats av API:et. |
api_requests_refused_total | Avvisade 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
| Symtom | Vad du ska kontrollera |
|---|---|
Anslutning nekad på 127.0.0.1:8377 | Lokal 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 sidan | Dess åtkomstgrupp är av. |
Läsning fungerar, skrivning avvisas med 401 | Slutpunkterna 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å engelska | Titlarna följer gränssnittets språk. Matcha på code från /taxonomy. |
accountId, startedAt eller at saknas | Integrationen skrevs för de tidigare namnen; se ovan. |
Vid ett problem med registrering eller med själva samtalet öppnar du Diagnostik.