> ## Documentation Index
> Fetch the complete documentation index at: https://help.verbu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API-kald under samtalen

> Lad agenten slå noget op eller skrive noget ned i jeres egne systemer, mens kunden stadig er på linjen.

Et API-kald lader agenten gå ind i et af jeres systemer midt i samtalen. Slå en ordre op, tjek en ledig tid, opret en sag. Kunden venter et sekund eller to og får et rigtigt svar i stedet for et løfte om at nogen ringer tilbage.

Du sætter dem op under **Actions** på din agent.

## Inden du bygger et

To spørgsmål afgør om det her er det rigtige værktøj.

**Skal agenten bruge svaret under samtalen?** Hvis oplysningen kan vente til bagefter, er en opsummeringsmail eller et webhook efter samtalen enklere, og det kan ikke få en kunde til at vente.

**Svarer systemet hurtigt?** Over to-tre sekunder er lang tid at være tavs i telefonen. Hvis jeres system er langsomt, så sig det i beskeden før udførelse, og sæt en ærlig timeout.

## Giv det et navn og en god beskrivelse

Beskrivelsen er ikke dokumentation. Det er sådan agenten afgør om den overhovedet skal kalde det, så skriv den til en kollega der aldrig har set jeres systemer.

<Tip>
  Skriv hvad det gør, hvad det skal bruge, og hvornår det skal bruges. "Slår en ordre op ud fra ordrenummer. Bruges når kunden henviser til en eksisterende ordre." er bedre end "Ordre-API".
</Tip>

Undgå at beskrive data som kaldet ikke returnerer. Hvis din beskrivelse lover leveringsdatoer, og svaret ikke indeholder nogen, bliver agenten ved med at lede efter dem og finder selv på noget når den ikke kan.

## Angiv jeres parametre

Tilføj hver værdi kaldet skal bruge under **Parametre**, med navn, type og en kort beskrivelse.

Det betyder mere end det ser ud til. Med parametre angivet udfylder agenten dem én ad gangen. Uden skal den sætte en hel klump JSON sammen ud fra din URL, og det rammer den oftere ved siden af.

|                  | Med parametre angivet              | Uden                       |
| ---------------- | ---------------------------------- | -------------------------- |
| Hvad agenten gør | Udfylder hver navngivet værdi      | Gætter et helt JSON-objekt |
| Forkerte værdier | Sjældnere, og lettere at få øje på | Sværere at spore           |
| Beskrivelser     | Guider hver værdi                  | Én lang instruktion        |

Værdier agenten ikke selv kan vide, som kundens telefonnummer eller samtalens sprog, behøver ikke være parametre. Skriv dem direkte i URL eller body som `{{caller_phone_number}}` og `{{language}}`, så udfylder kaldet dem fra samtalen.

## Svar-mapning

Lader du feltet stå tomt, får agenten **hele svaret**. Til de fleste opslag er det præcis det rigtige, og at mappe hvert felt i hånden ville være arbejde uden gevinst.

Map når du vil have en af tre ting:

* **Begræns hvad agenten ser.** Nyttigt når svaret indeholder felter der er irrelevante, eller som du helst ikke vil have agenten gentager over for en kunde.
* **Gem en værdi til senere.** Mappede værdier huskes resten af samtalen, så et senere kald eller et senere trin kan bruge dem.
* **Styr vejen videre.** I et flow kan en mappet værdi afgøre hvilken vej samtalen går.

Navngiv de værdier du vil have, og angiv stien hver af dem læser fra. Så snart du mapper noget, ser agenten de mappede værdier i stedet for hele svaret.

### Sådan skriver du det

Feltet til venstre er **variablens navn**, som du selv vælger. Feltet til højre er **stien** ind i JSON-svaret.

```json theme={null}
{
  "kunde_navn":   "data.customer.name",
  "ordre_status": "data.status"
}
```

| Sti                  | Læser                      |
| -------------------- | -------------------------- |
| `data.customer.name` | Et felt inde i svaret      |
| `orderId`            | Et felt øverst i svaret    |
| `slots[0].time`      | Første element i en liste  |
| `$`                  | Hele svaret, under ét navn |

Et `$.` foran virker også, så `$.data.customer.name` er lige så gyldigt. Den stil bruger vi selv i vores integrationer. Det gør ingen forskel for resultatet, så brug den du synes er lettest at læse.

<Warning>
  Feltet **Fortæl agenten hvad den skal gøre ved succes** er en instruktion, ikke et filter. Skriver du "nævn kun temperaturen", beder du agenten være diskret om data den stadig kan se. Hvis et felt ikke må nå agenten, så lad være med at mappe det.
</Warning>

### Mappede værdier bliver hængende

Et senere kald kan bruge en mappet værdi som `{{kunde_navn}}`, præcis som de andre variabler. Den gemmes også sammen med samtalen, så du kan se den bagefter.

Det gør det naturligt at kæde kald sammen: ét kald slår et kunde-id op, det næste bruger det.

## Sig noget mens det kører

Udfyld **Besked før udførelse** med en kort sætning agenten siger inden kaldet går i gang, for eksempel "Lige et øjeblik, jeg tjekker det." Uden den hører kunden stilhed, og i telefonen lyder stilhed som et afbrudt opkald.

Hold den kort og ærlig. Hvis kaldet typisk tager tre sekunder, så lov ikke at det tager ét.

## Tag stilling til fejl

Udfyld **Fortæl agenten hvad den skal gøre ved fejl**. Ellers finder agenten selv på noget, og det er præcis dér kunder får at vide at deres ordre er bekræftet, uden at der blev skrevet noget som helst.

<Tip>
  En god fejlinstruktion siger hvad der skete og hvad der så sker. "Sig at du ikke kunne få fat i bookingsystemet, og tilbyd at tage imod en besked så en kollega kan ringe tilbage."
</Tip>

## Timeout, genforsøg og send-og-fortsæt

| Indstilling            | Bruges til                                                                                                              |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Timeout**            | Hold den under hvad en kunde gider vente. Tre sekunder er allerede en lang pause.                                       |
| **Forsøg igen**        | Kun til opslag. Et genforsøg på noget der opretter en post kan oprette den to gange.                                    |
| **Udførelsestilstand** | **Vent på svar** når agenten skal bruge svaret. **Send og fortsæt** når den ikke skal, for eksempel en note til loggen. |

## I en samtale, eller i et flow

Det samme API-kald opfører sig forskelligt alt efter hvor du bruger det.

**Som en handling på agenten** beslutter agenten selv hvornår den kalder, ud fra din beskrivelse. Den udfylder parametrene fra samtalen.

**Som et trin i et flow** beslutter flowet. Det kører når kunden når det trin, og det udfylder værdierne ud fra det flowet allerede har samlet ind. Der er ingen beslutning at træffe og ingen beskrivelse der skal ramme rigtigt.

Trækker du et værktøj ind i et flow, bliver beskeden det siger undervejs kopieret over på trinnet, så du kan ændre ordlyden det ene sted uden at røre værktøjet alle andre steder.

## Når noget går galt

| Symptom                                         | Som regel                                                                      |
| ----------------------------------------------- | ------------------------------------------------------------------------------ |
| Agenten finder på detaljer API'et aldrig sendte | Beskrivelsen lover mere end svaret indeholder                                  |
| Agenten nævner data du ikke forventede          | Ingen svar-mapning, så den kan se hele svaret                                  |
| En mappet værdi er tom                          | Stien passer ikke til svaret. Tjek stavning og niveauer                        |
| Agenten kalder på skæve tidspunkter             | Beskrivelsen er for bred. Skriv hvornår det skal bruges, ikke kun hvad det gør |
| Lange pauser                                    | Ingen besked før udførelse, eller en timeout længere end kunden gider vente    |