External Provisioning

The softphone will call a web API to obtain SIP credentials. This allows providers to hide this information from their users. If you specify a separate subdomain for your users this can also be provisioned. For Whitelabel apps there are separate branding options for customising the provisioning form shown to your users. The provisioning form accepts a Username and Password. The standard login screens will not be shown in this case.

External Provisioning Url

If the provisioning url is specified as below

https://yourserver.com/provisioning/

The softphone will call the API as follows

GET /provisioning?username=jbloggs&password=7578743843&reprovision=false&deviceId=3kQs875391li29 HTTP/1.1
Host: provider.com
Connection: close
Cache-Control: max-age=0
User-Agent: SessionTalk/6.0.0

The username and password are taken from entries passed to the provisioning form.

The reprovision parameter will be false on first time setup only. The API is called whenever the app is restarted or returned to foreground after being background. The reprovision parameter allows for updating the provisioned accounts.

The deviceId is a unique identifier for a particular installation of the softphone. The deviceId cannot be used to identify a user's device. If the user reinstalls the softphone application the deviceId may change.

The web API should return a 2xx OK HTTP response with example JSON bodies shown below. First example is with required parameters. Second example includes optional parameters.

{
  "update": false,
  "sipaccounts": [
    { "sipusername": "user1", "sippassword": "29de?8", "transport": "UDP" }
  ],
  "errmsg": "custom error message"
}

Possible values for the transport parameter are UDP, TCP and TLS

{
  "update": false,
  "sipaccounts": [
    {
      "sipusername": "user1",
      "sippassword": "29de?8",
      "subdomain": "pbx",
      "authusername": "629456",
      "transport": "UDP",
      "srtp": "Enabled",
      "proxy": "proxy.sessiontalk.co.uk",
      "messaging": "Enabled",
      "video": "Enabled",
      "callrecording": "Enabled"
    }
  ],
  "errmsg": "custom error message"
}

To disable a setting simply pass "Disabled" for the parameter.

The update parameter determines whether the softphone will recreate the provisioned accounts. If the update parameter is false the softphone will ignore the sipaccounts parameter.

When the API has been called for a specific user the update parameter should be set to false to prevent unnecessary deleting and recreating of accounts on the softphone. The sipaccounts parameter is an array of objects consisting of the provisioned accounts. If provisioning a single account return a single object in the array. If using subdomains only the prefix should be returned by the API, this will then be prepended to the Domain setting specified in the portal to form a unique domain which is then provisioned to the user.

A custom error message may be specified that will be displayed in the softphone when accounts are unable to be provisioned.