Guider

Ta imot samtaler og bestem selv

Når noen ringer et av numrene dine, kan systemet ditt få hendelsen call.incoming mens det ringer hos innringeren, og bestemme hva som skal skje. Rekker du ikke å svare innen fristen, gjør nummeret det du har satt opp i dashbordet.

Slå det på for et nummer

Sett nummerets inboundMode til api. decideWithinSeconds er hvor lenge vi venter på deg før nummerets vanlige ruting tar over.

La systemet ditt bestemme over innkommende samtaler

curl -X PATCH "https://api.telkit.no/v1/numbers/0199e4a1-9d3c-7b45-a2e8-4f6b1c0d7e93" \  -H "Authorization: Bearer $TELKIT_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "inboundMode": "api",  "decideWithinSeconds": 15}'

const response = await fetch("https://api.telkit.no/v1/numbers/0199e4a1-9d3c-7b45-a2e8-4f6b1c0d7e93", {  method: "PATCH",  headers: {    Authorization: `Bearer ${process.env.TELKIT_API_KEY}`,    "Content-Type": "application/json",  },  body: JSON.stringify({    inboundMode: "api",    decideWithinSeconds: 15,  }),});const answer = await response.json();

Lag så en webhook for call.incoming, eller følg hendelsesstrømmen.

Når noen ringer

Innringeren hører at det ringer.
Du får call.incoming med callId, from, to, numberId, assignedTo og decideBy, tidspunktet fristen går ut.
Du sender en av handlingene under. Den første handlingen bestemmer.
Kommer ingen handling før decideBy, kjører nummerets ruting én gang (viderekobling, melding eller nettleseren). En handling etter det blir avvist med call_already_routed.

Handlingene

Kall	Betyr
`POST /v1/calls/:id/answer`	Svar. Innringeren hører en ventetone til neste handling, for eksempel en opplesning eller en meny.
`POST /v1/calls/:id/participants`	Koble til en medarbeider i appen din, et annet telefonnummer eller en AI-agent.
`POST /v1/calls/:id/offers`	La flere telefoner eller medarbeidere ringe samtidig. Den første som svarer, tar samtalen.
`POST /v1/calls/:id/transfer`	Sett over til et annet nummer. Mens det ringer, virker det som en viderekobling.
`POST /v1/calls/:id/move`	Flytt innringeren inn i en annen samtale, for eksempel et konferanserom eller en kø.
`POST /v1/calls/:id/reject`	Avvis. Samtalen slutter ubesvart, og ingenting blir trukket.

Koble til en medarbeider i appen din

Svaret har medarbeiderens connection, som nettleseren bruker for å koble seg til, slik som i guiden for utgående samtaler.

Koble en medarbeider i appen din til innringeren

curl -X POST "https://api.telkit.no/v1/calls/0199e4a3-1f6d-7a2b-8c55-3e9d0a7b4c21/participants" \  -H "Authorization: Bearer $TELKIT_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: innringer-kundeservice-4" \  -d '{  "participant": {    "kind": "app",    "externalRef": "kundeservice-4",    "displayName": "Kundeservice"  }}'

const response = await fetch("https://api.telkit.no/v1/calls/0199e4a3-1f6d-7a2b-8c55-3e9d0a7b4c21/participants", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.TELKIT_API_KEY}`,    "Content-Type": "application/json",    "Idempotency-Key": "innringer-kundeservice-4",  },  body: JSON.stringify({    participant: {      kind: "app",      externalRef: "kundeservice-4",      displayName: "Kundeservice",    },  }),});const answer = await response.json();

La den første som svarer, ta samtalen

curl -X POST "https://api.telkit.no/v1/calls/0199e4a3-1f6d-7a2b-8c55-3e9d0a7b4c21/offers" \  -H "Authorization: Bearer $TELKIT_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: innringer-tilbud-1" \  -d '{  "phones": [    "+4798765432"  ],  "ringSeconds": 20}'

const response = await fetch("https://api.telkit.no/v1/calls/0199e4a3-1f6d-7a2b-8c55-3e9d0a7b4c21/offers", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.TELKIT_API_KEY}`,    "Content-Type": "application/json",    "Idempotency-Key": "innringer-tilbud-1",  },  body: JSON.stringify({    phones: [      "+4798765432",    ],    ringSeconds: 20,  }),});const answer = await response.json();

Du får call.offer.accepted når noen tar samtalen, eller call.offer.expired når ingen gjorde det i tide.

Sett over eller flytt

Sett samtalen over til et annet nummer

curl -X POST "https://api.telkit.no/v1/calls/0199e4a3-1f6d-7a2b-8c55-3e9d0a7b4c21/transfer" \  -H "Authorization: Bearer $TELKIT_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: innringer-overfor-1" \  -d '{  "to": "+4798765432",  "kind": "cold"}'

const response = await fetch("https://api.telkit.no/v1/calls/0199e4a3-1f6d-7a2b-8c55-3e9d0a7b4c21/transfer", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.TELKIT_API_KEY}`,    "Content-Type": "application/json",    "Idempotency-Key": "innringer-overfor-1",  },  body: JSON.stringify({    to: "+4798765432",    kind: "cold",  }),});const answer = await response.json();

kind: "warm" lar deg snakke med den du setter over til, før du fullfører med POST /v1/calls/:id/transfer/complete. En flytting holder seg innenfor samme bedrift og profil.

Flytt innringeren inn i en annen samtale

curl -X POST "https://api.telkit.no/v1/calls/0199e4a3-1f6d-7a2b-8c55-3e9d0a7b4c21/move" \  -H "Authorization: Bearer $TELKIT_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: innringer-flytt-1" \  -d '{  "intoCallId": "0199e4a4-0a1b-7c2d-8e3f-4a5b6c7d8e9f"}'

const response = await fetch("https://api.telkit.no/v1/calls/0199e4a3-1f6d-7a2b-8c55-3e9d0a7b4c21/move", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.TELKIT_API_KEY}`,    "Content-Type": "application/json",    "Idempotency-Key": "innringer-flytt-1",  },  body: JSON.stringify({    intoCallId: "0199e4a4-0a1b-7c2d-8e3f-4a5b6c7d8e9f",  }),});const answer = await response.json();

Avvis

Avvis samtalen

curl -X POST "https://api.telkit.no/v1/calls/0199e4a3-1f6d-7a2b-8c55-3e9d0a7b4c21/reject" \  -H "Authorization: Bearer $TELKIT_API_KEY"

const response = await fetch("https://api.telkit.no/v1/calls/0199e4a3-1f6d-7a2b-8c55-3e9d0a7b4c21/reject", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.TELKIT_API_KEY}`,  },});const answer = await response.json();

Telefonmeny: spør og lytt

Svar først, og spør deretter innringeren. gather leser opp spørsmålet og lytter etter tastetrykk, tale eller begge. Med choices finner vi selv ut hvilket valg innringeren sa.

Svar på samtalen

curl -X POST "https://api.telkit.no/v1/calls/0199e4a3-1f6d-7a2b-8c55-3e9d0a7b4c21/answer" \  -H "Authorization: Bearer $TELKIT_API_KEY"

const response = await fetch("https://api.telkit.no/v1/calls/0199e4a3-1f6d-7a2b-8c55-3e9d0a7b4c21/answer", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.TELKIT_API_KEY}`,  },});const answer = await response.json();

Spør innringeren og lytt etter tast eller tale

curl -X POST "https://api.telkit.no/v1/calls/0199e4a3-1f6d-7a2b-8c55-3e9d0a7b4c21/gather" \  -H "Authorization: Bearer $TELKIT_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: innringer-meny-1" \  -d '{  "prompt": {    "text": "Trykk 1 eller si salg. Trykk 2 eller si kundeservice.",    "voice": "no_female"  },  "input": [    "dtmf",    "speech"  ],  "maxDigits": 1,  "timeoutSeconds": 8,  "choices": [    {      "id": "salg",      "phrases": [        "salg"      ]    },    {      "id": "kundeservice",      "phrases": [        "kundeservice",        "support"      ]    }  ],  "language": "no"}'

const response = await fetch("https://api.telkit.no/v1/calls/0199e4a3-1f6d-7a2b-8c55-3e9d0a7b4c21/gather", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.TELKIT_API_KEY}`,    "Content-Type": "application/json",    "Idempotency-Key": "innringer-meny-1",  },  body: JSON.stringify({    prompt: {      text: "Trykk 1 eller si salg. Trykk 2 eller si kundeservice.",      voice: "no_female",    },    input: [      "dtmf",      "speech",    ],    maxDigits: 1,    timeoutSeconds: 8,    choices: [      {        id: "salg",        phrases: [          "salg",        ],      },      {        id: "kundeservice",        phrases: [          "kundeservice",          "support",        ],      },    ],    language: "no",  }),});const answer = await response.json();

Når innringeren har svart, eller tiden er ute, får du call.gather.completed:

Felt	Betyr
`outcome`	`digits`, `speech`, `timeout` eller `stopped`.
`digits`	Tastene innringeren trykket.
`transcript`	Det innringeren sa.
`choice`	Id-en til valget i `choices` som passet, ellers `null`.

Tastetrykk utenom en meny kommer som call.dtmf.received.

Råd

Svar på webhooken med 2xx med en gang, og send handlingen som et eget kall. Da teller ikke en treg handling mot leveringen av hendelsen.
Sett en kort frist hvis du vil at innringeren skal vente lite, og la nummerets ruting være en trygg reserve.
Bruk Idempotency-Key med callId i nøkkelen, så et nytt forsøk ikke kobler til to ganger.