Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

sipgate logo python outgoing call example

In order to demonstrate how to initiate an outgoing call, we queried the /sessions/calls endpoint of the sipgate REST API.

For further information regarding the sipgate REST API please visit


  • python3
  • pip3
  • VoIP client

How To Use

Navigate to the project's root directory.

Install dependencies:

$ pip3 install -r requirements.txt

In order to run the code you must set the following variables in

token_id = 'YOUR_TOKEN_ID'
token = 'YOUR_TOKEN'

caller = 'DIALING_DEVICE';


The token should have the following scopes:

  • sessions:calls:write

For more information about personal access token, visit

The device_id uniquely identifies the phone extension which establishes the phone connection, this variable is needed only when the caller is a phone number and not a device extension. Further explanation is given in the section Web Phone Extensions. Nevertheless you can still use both as device extension, but in this case the device_id will be ignored.

Use callee and caller_id to set the recipient phone number and the displayed caller number respectively.

Run the application:

$ python3
How It Works

The following explanations lay out how the code example works. There is no need for you to change anything unless you want to do something different.

The sipgate REST API is available under the following base URL:

base_url = ''

The API expects request data in JSON format. Thus the Content-Type header is set to:

headers = {
	'Content-Type': 'application/json'

The request body contains the fields: deviceId, caller, callee and callerId as specified above.

requestBody = {
		"deviceId": device_id,
		"callee": callee,
		"caller" : caller,
		"callerId" : caller_id

We use the python package 'requests' for request generation and execution. The post function takes the following arguments:

  • request URL
  • headers
  • authorization header
  • request body

The request URL consists of the base URL defined above and the endpoint /sessions/calls. The function HTTPBasicAuth from the 'requests' package takes the credentials and generates the required Basic Auth header as authorization header (for more information on Basic Auth see our code example).

response =
	base_url + '/sessions/calls',
	auth=requests.auth.HTTPBasicAuth(token_id, token),

Web Phone Extensions

A Web Phone extension consists of one letter followed by a number (e.g. 'e0'). The sipgate API uses the concept of Web Phone extensions to identify devices within your account that are enabled to initiate calls.

Depending on your needs you can choose between the following phone types:

phone type letter
voip phone e
external phone x
mobile phone y

You can find out what your extension is as follows:

  1. Log into your sipgate account
  2. Use the sidebar to navigate to the Phones (Telefone) tab
  3. Click on the device from which you want the Web Phone extension (deviceId)
  4. The URL of the page this takes you to should have the form{...}/devices/{deviceId} where {deviceId} is your Web Phone extension

Common Issues

API returns 200 OK but no call gets initiated

Possible reasons are:

  • your phone is not connected
  • caller does not match your phones Web Phone extension

HTTP Errors

reason errorcode
bad request (e.g. request body fields are empty or only contain spaces, timestamp is invalid etc.) 400
token_id and/or token are wrong 401
insufficient account balance 402
no permission to use specified Web Phone extension (e.g. user password must be reset in web app) 403
wrong REST API endpoint 404
wrong request method 405
wrong or missing Content-Type header with application/json 415


Contact Us

Please let us know how we can improve this example. If you have a specific feature request or found a bug, please use Issues or fork this repository and send a pull request with your improvements.


This project is licensed under The Unlicense (see LICENSE file).

External Libraries

This code uses the following external libraries | @sipgateio | API-doc


A demonstration of how to initiate a call using the sipgate REST API.







No releases published


No packages published