IVRAPI dla platform CRM

Część 1. Uruchomienie platformy oraz przygotowanie użytkowników do realizacji połączeń

Wprowadzenie

Integracja platformy CRM z IVRAPI rozpoczyna się od utworzenia po stronie IVRAPI profilu klienta oraz konta administratora.

Administrator otrzymuje indywidualny klucz API, który umożliwia komunikację z platformą IVRAPI na najwyższym poziomie uprawnień.

Klucz API administratora zapewnia dostęp do wszystkich usług dostępnych dla danego klienta oraz umożliwia zarządzanie użytkownikami i konfiguracją usług.

Uprawnienia administratora

Administrator może:

• inicjować połączenia telefoniczne,
• pobierać historię połączeń,
• pobierać nagrania rozmów,
• wysyłać wiadomości SMS,
• pobierać historię wiadomości SMS,
• inicjować kampanie VoiceBot,
• wysyłać powiadomienia głosowe,
• pobierać statystyki i raporty,
• zarządzać użytkownikami,
• zarządzać numerami wirtualnymi,
• korzystać ze wszystkich usług przypisanych do klienta.

Poziom 1 – Inicjowanie, rejestracja i nagrywanie połączeń

Pierwszym etapem integracji jest przygotowanie użytkowników, którzy będą realizowali połączenia telefoniczne za pośrednictwem platformy IVRAPI.

Użytkownicy nie muszą logować się do platformy IVRAPI ani aktywnie z niej korzystać. Ich utworzenie jest wymagane w celu przypisania numerów wirtualnych wykorzystywanych podczas realizacji połączeń.

Krok 1. Utworzenie użytkownika

Administrator tworzy użytkownika za pomocą endpointu:

POST https://api.ivrapi.com/api/users

Przykładowe wywołanie

curl -X 'POST' \
  'https://api.ivrapi.com/api/users' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: sk-xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "jan.kowalski@advicos.com",
    "password": "superTajneHaslo123",
    "name": "Jan Kowalski",
    "phoneNumber": "739183045",
    "passwordExpirationPeriod": 30,
    "role": "User",
    "mpk": "77B001",
    "sendPassword": true,
    "skipPhoneVerification": true,
    "isEmviphoneActive": true
  }'

Przykładowa odpowiedź

{
  "email": "jan.kowalski@advicos.com",
  "phoneNumber": "739183045",
  "name": "Jan Kowalski",
  "active": true,
  "password": "$2b$10$kekcJ0jtaFtJtQHFwDOl7.Tztlhjy61Hn49n.TZbLEukCQS.wgt/m",
  "mpk": "77B001",
  "passwordExpirationPeriod": 30,
  "phoneNumberConfirmed": true,
  "isEmviphoneActive": true,
  "role": {
    "id": 2,
    "name": "User",
    "displayName": "Użytkownik",
    "description": null
  },
  "client": {
    "id": 3,
    "name": "ADVICOS POLAND sp. z o.o.",
    "agendialerClientId": 1,
    "privatePerson": false,
    "street": "Leśna 56",
    "postCode": "87-125",
    "city": "Silno",
    "tin": null
  },
  "emailConfirmed": true,
  "id": 1135,
  "languageCode": "pl",
  "createdAt": "2026-06-15T07:40:22.612Z",
  "passwordChangedAt": "2026-06-15T07:40:22.612Z",
  "blockTo": "2026-06-15T07:40:22.612Z"
}

Krok 2. Aktualizacja danych użytkownika

Po utworzeniu użytkownika administrator może aktualizować jego dane. Do modyfikacji wykorzystywany jest identyfikator użytkownika zwrócony podczas tworzenia konta.

PUT https://api.ivrapi.com/api/users/{id}

Przykład zmiany numeru telefonu

curl -X 'PUT' \
  'https://api.ivrapi.com/api/users/1135' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: sk-xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumber": "739183044"
  }'

Przykładowa odpowiedź

{
  "id": 1135,
  "email": "jan.kowalski@advicos.com",
  "name": "Janek Kowalski",
  "languageCode": "pl",
  "active": true,
  "emailConfirmed": true,
  "createdAt": "2026-06-15T07:40:22.612Z",
  "passwordExpirationPeriod": 30,
  "phoneNumber": "739183044",
  "phoneNumberConfirmed": false,
  "mpk": "77B001",
  "isEmviphoneActive": false,
  "client": {
    "id": 3,
    "name": "ADVICOS POLAND sp. z o.o.",
    "agendialerClientId": 1,
    "privatePerson": false,
    "street": "Leśna 56",
    "postCode": "87-125",
    "city": "Silno",
    "tin": null
  },
  "role": {
    "id": 2,
    "name": "User",
    "displayName": "Użytkownik",
    "description": null
  },
  "vnumber": null
}

Krok 3. Listowanie numerów wirtualnych

Przed przypisaniem numeru wirtualnego do użytkownika należy pobrać listę numerów dostępnych dla klienta.

GET https://api.ivrapi.com/api/vnumbers

Przykładowe wywołanie

curl -X 'GET' \
  'https://api.ivrapi.com/api/vnumbers' \
  -H 'accept: */*' \
  -H 'X-Api-Key: sk-xxxxxxxxxxxxxxxxxxxxxxxx'

Przykładowa odpowiedź

{
  "items": [
    {
      "id": 924,
      "vnumber": "739183015",
      "createdAt": "2025-05-29T15:07:22.871Z",
      "scenarios": null,
      "user": null,
      "client": {
        "id": 3,
        "name": "ADVICOS POLAND sp. z o.o.",
        "agendialerClientId": 1,
        "privatePerson": false,
        "street": "Leśna 56",
        "postCode": "87-125",
        "city": "Silno",
        "tin": null
      },
      "bot": null,
      "smsSender": {
        "id": 788,
        "name": "48739183015",
        "createdAt": "2025-05-29T15:07:22.868Z"
      },
      "clientId": 3,
      "userId": null
    }
  ],
  "meta": {
    "totalItems": 125,
    "itemCount": 10,
    "itemsPerPage": 10,
    "totalPages": 13,
    "currentPage": 1
  }
}

Jak rozpoznać wolny numer?

Najprostszym sposobem jest sprawdzenie pola userId.

Jeżeli wartość wynosi null, numer nie jest przypisany do żadnego użytkownika i może zostać wykorzystany.

{
  "id": 924,
  "vnumber": "739183015",
  "userId": null
}

Po przypisaniu numeru do użytkownika pole userId będzie zawierało identyfikator użytkownika.

{
  "id": 924,
  "vnumber": "739183015",
  "userId": 1135
}

Oznacza to, że numer został przypisany do użytkownika o identyfikatorze 1135 i nie może zostać wykorzystany przez innego użytkownika.

Krok 4. Przypisanie numeru wirtualnego do użytkownika

Po pobraniu listy numerów wirtualnych należy sprawdzić, który numer jest wolny. Numer można przypisać do użytkownika, jeżeli pole userId ma wartość null.

{
  "id": 924,
  "vnumber": "739183015",
  "userId": null
}

Jeżeli numer jest wolny, można przypisać go do użytkownika za pomocą endpointu aktualizacji użytkownika.

PUT https://api.ivrapi.com/api/users/{id}

Gdzie {id} oznacza identyfikator użytkownika w systemie IVRAPI.

Przykładowe wywołanie

curl -X 'PUT' \
  'https://api.ivrapi.com/api/users/1135' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: sk-xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "vnumberId": 924
  }'

Parametry

Przykładowa odpowiedź

{
  "id": 1135,
  "email": "jan.kowalski@advicos.com",
  "name": "Janek Kowalski",
  "languageCode": "pl",
  "active": true,
  "emailConfirmed": true,
  "createdAt": "2026-06-15T07:40:22.612Z",
  "passwordExpirationPeriod": 30,
  "phoneNumber": "739183044",
  "phoneNumberConfirmed": false,
  "mpk": "77B001",
  "blockTo": "2026-06-15T07:40:22.612Z",
  "isEmviphoneActive": false,
  "client": {
    "id": 3,
    "name": "ADVICOS POLAND sp. z o.o.",
    "agendialerClientId": 1,
    "privatePerson": false,
    "street": "Leśna 56",
    "postCode": "87-125",
    "city": "Silno",
    "tin": null
  },
  "role": {
    "id": 2,
    "name": "User",
    "displayName": "Użytkownik",
    "description": null
  },
  "vnumber": {
    "id": 924
  }
}

Po wykonaniu tej operacji użytkownik posiada przypisany numer wirtualny i może być wykorzystywany w kolejnych procesach, takich jak inicjowanie połączeń telefonicznych, rejestracja rozmów oraz obsługa usług powiązanych z numerem.

Krok 5. Inicjowanie połączenia telefonicznego

Po utworzeniu użytkownika, przypisaniu mu numeru telefonicznego oraz numeru wirtualnego można zainicjować połączenie telefoniczne za pośrednictwem IVRAPI.

Do inicjowania połączeń wykorzystywany jest endpoint:

POST https://api.ivrapi.com/api/connections

Przykładowe wywołanie

curl -X 'POST' \
  'https://api.ivrapi.com/api/connections' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: sk-xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "targetNumber": "502131658",
    "maxConnectionRetries": 3,
    "userNumber": "502131638",
    "direction": "a2c",
    "virtualNumber": "739183015",
    "clipForAgent": "739183015"
  }'

Parametry requestu

Kierunek połączenia (direction)

Parametr direction określa kolejność zestawiania połączenia.

Najważniejsze zasady walidacji

Podczas inicjowania połączenia system weryfikuje, czy wskazane numery istnieją w bazie IVRAPI oraz czy są przypisane do właściwego klienta. Jeżeli którykolwiek z numerów jest niepoprawny lub nie istnieje, API zwróci błąd.

Przykładowa odpowiedź

Poniżej pokazano uproszczoną odpowiedź API, zawierającą tylko pola istotne z punktu widzenia tutoriala.

{
  "id": 557889,
  "targetNumber": "502131658",
  "createdAt": "2026-06-15T08:18:09.010Z",
  "callStart": "2026-06-15T08:18:09.009Z",
  "direction": "a2c",
  "sid": "df533e98-1758-4543-8fcc-d741d1b128d9",
  "clip": "502131658",
  "status": {
    "id": 1,
    "name": "init",
    "content": [
      {
        "languageCode": "pl",
        "text": "zainicjowano"
      }
    ]
  }
}

Najważniejsze pola odpowiedzi

Przykładowe błędy walidacji

Jeżeli wskazany numer wirtualny nie istnieje w systemie IVRAPI, API może zwrócić odpowiedź:

{
  "statusCode": 400,
  "message": "Specified virtual number does not exist"
}

Jeżeli wskazany numer użytkownika nie istnieje w systemie IVRAPI, API może zwrócić odpowiedź:

{
  "statusCode": 400,
  "message": "Cannot found user with specified number"
}

Po poprawnym zainicjowaniu połączenia system zwraca identyfikator połączenia oraz status init. Identyfikator połączenia może być następnie wykorzystywany do śledzenia statusu, pobierania informacji o przebiegu rozmowy oraz dalszej analizy komunikacji.

Krok 6. Pobieranie statusu połączenia

Po zainicjowaniu połączenia system CRM może pobierać aktualny status połączenia oraz informacje o jego przebiegu. Do odczytu danych wykorzystywany jest identyfikator połączenia zwrócony podczas jego inicjowania.

GET https://api.ivrapi.com/api/connections?id={connectionId}

Przykładowe wywołanie

curl -X 'GET' \
  'https://api.ivrapi.com/api/connections?id=557889' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: sk-xxxxxxxxxxxxxxxxxxxxxxxx'

Przykładowa odpowiedź

Poniżej pokazano uproszczoną odpowiedź API, zawierającą tylko pola istotne z punktu widzenia tutoriala.

{
  "items": [
    {
      "id": 557889,
      "targetNumber": "502131658",
      "createdAt": "2026-06-15T08:18:09.010Z",
      "totalCallDuration": 35,
      "callStart": "2026-06-15T08:18:17.000Z",
      "callEnd": "2026-06-15T08:18:52.000Z",
      "agentNumber": "502131638",
      "direction": "a2c",
      "sid": "df533e98-1758-4543-8fcc-d741d1b128d9",
      "agent": {
        "id": 1017,
        "name": "Maciej Zasadzki",
        "groupName": "USER CLIP",
        "phoneNumber": "502131638",
        "phoneNumberConfirmed": true,
        "active": true
      },
      "status": {
        "id": 5,
        "name": "busy",
        "content": [
          {
            "languageCode": "pl",
            "text": "numer zajęty"
          }
        ]
      },
      "isBotCall": false
    }
  ],
  "meta": {
    "totalItems": 1,
    "itemCount": 1,
    "itemsPerPage": 10,
    "totalPages": 1,
    "currentPage": 1
  }
}

Najważniejsze pola odpowiedzi

Interpretacja statusu

W przedstawionym przykładzie status połączenia ma wartość:

{
  "status": {
    "name": "busy",
    "content": [
      {
        "languageCode": "pl",
        "text": "numer zajęty"
      }
    ]
  }
}

Oznacza to, że połączenie zostało zakończone statusem busy, czyli numer docelowy był zajęty.

Przykładowe statusy połączeń

Powiązanie połączenia z rekordem CRM

Podczas inicjowania połączenia rekomendowane jest przekazywanie identyfikatora klienta lub użytkownika z zewnętrznego systemu CRM. Dzięki temu połączenie można jednoznacznie powiązać z rekordem klienta po stronie CRM.

Mechanizm ten ułatwia:

• wyszukiwanie połączeń dla konkretnego klienta,
• powiązanie historii połączeń z kartą klienta,
• odnajdywanie komunikacji po zmianie danych klienta,
• synchronizację historii komunikacji między CRM i IVRAPI,
• raportowanie aktywności użytkowników względem klientów.

Przykład rozszerzenia requestu inicjującego połączenie

{
  "targetNumber": "502131658",
  "maxConnectionRetries": 3,
  "userNumber": "502131638",
  "direction": "a2c",
  "virtualNumber": "739183015",
  "clipForAgent": "739183015",
  "externalClientId": "CRM-123456",
  "externalUserId": "USR-98765"
}

Znaczenie pól zewnętrznych

W kolejnych zapytaniach identyfikatory zewnętrzne mogą być wykorzystywane do wyszukiwania i dopasowywania rekordów po stronie CRM, bez konieczności opierania się wyłącznie na numerach telefonów.

Następny krok

Po sprawdzeniu statusu połączenia można przejść do pobierania szczegółowych informacji o rozmowie, nagraniach oraz pełnej historii komunikacji.

Krok 7. Pobieranie nagrania rozmowy

Po zakończeniu rozmowy system CRM może pobrać nagranie połączenia zapisane w IVRAPI.

Do pobrania nagrania wykorzystywany jest identyfikator sesji połączenia (SID), który zwracany jest podczas inicjowania połączenia oraz dostępny podczas pobierania statusu połączenia.

Przykładowy identyfikator SID

{
  "sid": "df533e98-1758-4543-8fcc-d741d1b128d9"
}

Endpoint

GET https://api.ivrapi.com/api/connections/records/{sid}

Przykładowe wywołanie

curl -X 'GET' \
  'https://api.ivrapi.com/api/connections/records/df533e98-1758-4543-8fcc-d741d1b128d9' \
  -H 'accept: */*' \
  -H 'X-Api-Key: sk-xxxxxxxxxxxxxxxxxxxxxxxx'

Parametry

Zastosowanie nagrań

Nagranie może zostać:

• zapisane w historii kontaktu CRM,
• wykorzystane do kontroli jakości rozmów,
• przekazane do systemów AI w celu transkrypcji,
• wykorzystane do analiz sprzedażowych i obsługowych,
• dołączone do dokumentacji klienta.

Powiązanie z CRM

Rekomendowane jest zapisanie identyfikatora SID w rekordzie klienta lub aktywności CRM już podczas inicjowania połączenia. Dzięki temu możliwe jest późniejsze pobranie nagrania, transkrypcji oraz pełnej historii komunikacji.

Krok 8. Generowanie i pobieranie transkrypcji rozmowy

Podobnie jak pozostałe usługi IVRAPI, funkcja transkrypcji wykorzystuje autoryzację za pomocą klucza API przekazywanego w nagłówku X-Api-Key. Wszystkie przykłady przedstawione w tej dokumentacji wykorzystują ten sam mechanizm autoryzacji.

Transkrypcja rozmowy jest procesem wykonywanym na podstawie nagrania rozmowy. W pierwszym kroku system CRM zleca wygenerowanie transkrypcji metodą POST.

Ze względu na długość nagrania oraz czas potrzebny na przetworzenie rozmowy, transkrypcja może nie być dostępna natychmiast. W takim przypadku API zwraca uproszczoną odpowiedź z informacją, że zadanie zostało przyjęte do realizacji i będzie przetwarzane asynchronicznie.

Krok 8.1. Zlecenie wygenerowania transkrypcji

POST https://api.ivrapi.com/api/connections/{connectionSid}/transcription

Przykładowe wywołanie POST

curl -X 'POST' \
  'https://api.ivrapi.com/api/connections/df533e98-1758-4543-8fcc-d741d1b128d9/transcription' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: sk-xxxxxxxxxxxxxxxxxxxxxxxx'

Przykładowa odpowiedź POST

{
  "id": 2548,
  "content": null,
  "done": false
}

Interpretacja odpowiedzi POST

Krok 8.2. Pobranie gotowej transkrypcji

GET https://api.ivrapi.com/api/connections/{connectionSid}/transcription

Przykładowe wywołanie GET

curl -X 'GET' \
  'https://api.ivrapi.com/api/connections/df533e98-1758-4543-8fcc-d741d1b128d9/transcription' \
  -H 'accept: */*' \
  -H 'X-Api-Key: sk-xxxxxxxxxxxxxxxxxxxxxxxx'

Przykładowa odpowiedź GET

{
  "id": 2548,
  "content": [
    {
      "alternatives": [
        {
          "transcript": "dzień dobry",
          "confidence": 0.9634110927581787
        }
      ],
      "channelTag": 1,
      "resultEndTime": {
        "seconds": "4",
        "nanos": 20000000
      },
      "languageCode": "pl-pl"
    },
    {
      "alternatives": [
        {
          "transcript": "Tak słucham",
          "confidence": 0.9634111523628235
        }
      ],
      "channelTag": 1,
      "resultEndTime": {
        "seconds": "10",
        "nanos": 520000000
      },
      "languageCode": "pl-pl"
    },
    {
      "alternatives": [
        {
          "transcript": "Dziękuję bardzo do usłyszenia",
          "confidence": 0.9468808174133301
        }
      ],
      "channelTag": 2,
      "resultEndTime": {
        "seconds": "59",
        "nanos": 970000000
      },
      "languageCode": "pl-pl"
    },
    {
      "alternatives": [
        {
          "transcript": "Do usłyszenia",
          "confidence": 0.8341746926307678
        }
      ],
      "channelTag": 1,
      "resultEndTime": {
        "seconds": "60",
        "nanos": 150000000
      },
      "languageCode": "pl-pl"
    }
  ],
  "done": true
}

Interpretacja odpowiedzi GET

Wartość done: true oznacza, że transkrypcja została wygenerowana i jest dostępna w polu content.

Transkrypcja dwukanałowa

Nagrania rozmów w IVRAPI są dwukanałowe. Dzięki temu system CRM może rozpoznać, która strona rozmowy wypowiedziała konkretny fragment.

Zastosowanie transkrypcji w CRM

• zapis treści rozmowy w historii kontaktu,
• automatyczne tworzenie notatek po rozmowie,
• wyszukiwanie ustaleń z klientem,
• analiza jakości obsługi,
• analiza intencji klienta,
• przekazanie treści rozmowy do dalszej analizy AI.

Rekomendacja integracyjna

System CRM powinien zapisać identyfikator sid razem z rekordem połączenia. Ten sam identyfikator jest wykorzystywany zarówno do pobierania nagrania, jak i do zlecania oraz pobierania transkrypcji.

Następny krok

Po uzyskaniu transkrypcji można przejść do analizy treści rozmowy, automatycznego tworzenia notatek oraz zapisu wyników analizy w systemie CRM.