Skip to content
A demonstration of how to initiate a call using the sipgate REST API.
Python
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore
LICENSE
README.md
outgoing_call.py
requirements.txt
setup.py

README.md

sipgate logo

sipgate.io 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 https://api.sipgate.com/v2/doc

Prerequisites

  • 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 outgoing_call.py:

username = 'YOUR_EMAIL'
password = 'YOUR_PASSWORD'

device_id = 'YOUR_SIPGATE_DEVICE_EXTENSION'
caller = 'DIALING_DEVICE';

callee = 'YOUR_RECIPIENT_PHONE_NUMBER'
caller_id = 'DISPLAYED_CALLER_NUMBER'

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 outgoing_call.py
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 = 'https://api.sipgate.com/v2'

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 = requests.post(
	base_url + '/sessions/calls',
	headers=headers,
	auth=requests.auth.HTTPBasicAuth(username, password),
	json=requestBody
)

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 https://app.sipgate.com/{...}/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
username and/or password 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

Related

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.

License

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

External Libraries

This code uses the following external libraries


sipgate.io | @sipgateio | API-doc

You can’t perform that action at this time.