API for dealers and partners

Setup guides / For developers and partners (API use) / API for dealers and partners

With Zadarma’s API you can offer telecom services to your clients without the need for them to register at Zadarma. Moreover, your clients will be able to receive telecommunication under your brand, allowing you to Whitelabel this service.

You can offer telecommunication services not as a separate service, but as a part of your system, allowing you to tightly integrate with it.

In short, your clients will be able to make and receive calls from your web interface, using all Zadarma PBX features and more.

All capabilities and methods API Zadarma

To work with the described methods you first need to receive access to Zadarma dealer account. If you do not have an account, create a ticket to the finance department.

Integration features:

  • Creating new Zadarma user account from the parent dealer account and managing these accounts
  • Balance funds transfer between dealer and subsidiary accounts
  • Virtual number connection
  • Virtual PBX creation and set up
  • API keys reception for user account
  • Webhook link setup for managing PBX incoming calls
  • WebRTC widget creation for user accounts etc.

Telecommunication connection steps for your clients:

1. User registration (Creating a new Zadarma account) is performed via method POST /v1/reseller/users/registration/new/ .

To complete user registration a confirmation is required via method POST /v1/reseller/users/registration/confirm/ .

To receive test funds and an ability to add more funds, user contact number has to be added and confirmed. Number can be added using method POST /v1/reseller/users/phones/add/ .

To confirm a number we send an SMS message with a code /v1/reseller/users/phones/prove_by_sms, the user enters the code on your website and you pass it on via method /v1/reseller/users/phones/confirm .

2. Funds transfer from dealer balance to user account balance is done via method GET /v1/reseller/users/topup/ .

3. Virtual number connection is described in details here, simply add to the method parameter user_id with identification of the user the action is made for (number connection, document uploading etc).

4. Using method POST /v1/pbx/create/ you can create Zadarma virtual PBX for your user.

5. Create a PBX extension number for each employee using method POST /v1/pbx/internal/create/ .

Enable call recordings to the cloud for PBX extension numbers using method PUT /v1/pbx/internal/recording/ .

6. To route PBX incoming calls voice menu (IVR) and scenarios (menu items – groups of extension numbers that receive calls) can be used. Method /v1/pbx/create/ created PBX with minimal settings: 1 extension number and 1 scenario “without pressing” (that receives all calls by default). Further you can create a required number of menu items and scenarios within the menu.

Scenarios are also required for dynamic voice menu, if you want to simultaneously route calls to more than one extension number. You can create a new scenario using method /v1/pbx/ivr/scenario/create/ , see the list /v1/pbx/ivr/scenario/ and delete /v1/pbx/ivr/scenario/delete/ . When creating a scenario, a list of extension numbers that receive a call and a key that activates a scenario are set. If you are not planning to specify a key in the settings and use a dynamic menu, set a parameter push_button over 11.

7. Audio file for voice menu can be uploaded to virtual PBX via method POST /v1/pbx/ivr/sounds/upload

Audio file size for uploading – 5MB, possible formats - MP3, WAV.

8. API access. The user can also use API to interact with their account or to integrate with third-party services or CRM systems, to do so the keys need to be generated. The user can generate the keys themselves in the personal account, or the dealer can receive these keys using method POST /v1/reseller/users/api_key/ with parameter user_id - user id number. The response will contain user's "key" and "secret" for access to their API.

You can also set a URL that will receive notifications about calls to user’s virtual PBX using method POST /v1/pbx/callinfo/url/ and a separate url for other notifications (contact actualization, call tracking, SMS and speech analytics) using method POST /v1/pbx/webhooks/url/ parameters are the same for both requests url - link and user_id - user id number.

9. For managing dynamic voice menu and client linkling calls, you can use an existing PHP library available in our Github or use your solution with the help of our call notification system, more on that here.

10. Virtual PBX integration with a third-part CRM system is described in details in a separate manual here.

11. For clients to make calls via your interface, use WebRTC widget according to the instructions. You can also offer to connect any apps or equipment via SIP protocol. Connection parameters (login-password) you can receive via method /v1/pbx/internal/