API docs by Redocly

Cloud SIP UA Service - Getting Started

Download OpenAPI specification:Download

Getting Started

Provisioning of Cloud SIP UA devices

Before using the Cloud SIP UA Service, each device must be provisioned with the required properties. These properties define the device's identity and how it will interact with the SIP infrastructure. For Cloud SIP UA devices, the following configuration parameters are essential:

Required Device Properties

  • Authentication Type (authType)

    – Set this to disabled. Cloud SIP UA devices do not perform SIP authentication.

  • Device ID (deviceId)

    – This is the SIP user, typically a phone number, that identifies the Cloud UA. It will be used as the calling party number and forms the user part of the SIP URI.

  • Device CLI (deviceCLI)

    – Not applicable for Cloud SIP UA. Leave this field empty.

  • Device Type (deviceType)

    – Set this to alarmUnit for Cloud SIP UA devices.

  • MAC Address (macAddress)

    – Not applicable for Cloud SIP UA. Leave this field empty.

  • Description (description)

    – Optional free-text field for internal use or notes.

There is no need to provision any service data for Cloud SIP UA devices.

Using web portal

Create Cloud SIP UA Image

To provision devices via the web portal:

  1. Log in to the Developer Portal

    Navigate to the iotcomms.io Developer Portal and sign in.

  2. Go to Devices Management page

    Go to *Configuration → Devices* or visit [/configuration/devices].

  3. Create a New Device

    Click *Create Device* and enter the required properties listed above.

  4. Click Create button to save the device

Using API

To provision a Cloud SIP UA device programmatically, use the iotcomms.io Provisioning API. This method is ideal for automation and large-scale deployments.

Endpoint:

PUT api.<region>.iotcomms.io/provisioning/device/{domain}

Headers:

Authorization: Bearer <your_jwt_token>
Content-Type: application/json

Request Body:

{
    "deviceId": "1234567890",
    "authType": "disabled",
    "deviceType": "alarmUnit",
    "description": "Optional description"
}

Field Descriptions:

  • deviceId: The SIP user identifier, typically a phone number, representing the calling party number and forming the user part of the SIP URI.

  • authType: Set to "disabled" as Cloud SIP UA devices do not perform SIP authentication.

  • deviceType: Set to "alarmUnit" for Cloud SIP UA devices.

  • description: Optional free-text field for internal use or notes.

Example cURL Command:

curl -X PUT "https://api.eu-north-1.iotcomms.io/provisioning/device/yourdomain.iotcomms.io" 

    -H "Authorization: Bearer <your_jwt_token>" 

    -H "Content-Type: application/json" 

    -d '{
            "deviceId": "1234567890",
            "authType": "disabled",
            "deviceType": "alarmUnit",
            "description": "Test device"
        }'

Replace yourdomain.iotcomms.io with your actual domain and <your_jwt_token> with a valid JWT token.

For more details, refer to the Provisioning API documentation.

Example: Receive a call

Before a Cloud SIP UA device can receive calls, a SIP trunk must be provisioned in the SIP Core service. You can configure this in the web portal under [/configuration/trunks].

The following steps illustrate the process of receiving a SIP call through the Cloud SIP UA Service:

  1. Inbound call is received

    A SIP INVITE is received on the Cloud SIP UA Service via the configured SIP trunk. The service responds with a SIP 100 Trying.

  2. Trigger callback to application

    The service sends a POST /newRemoteCall callback to the customer application. The application responds with HTTPS 200 OK. This callback contains media negotiation information, such as codec, remote IP, and port where the application should send RTP media.

  3. Send ringback tone

    The customer application calls the POST /remotecallringback API to trigger a SIP 180 Ringing response. The service responds with HTTPS 200 OK.

  4. Answer the call

    When the application is ready, it calls the POST /answerremotecall API. The service responds with HTTPS 200 OK and sends a SIP 200 OK to the caller. This SIP response includes codec and media information for receiving RTP from the application.

  5. RTP media flow begins

    Bi-directional RTP media is now exchanged between the calling party and the application.

Call Termination Scenarios

If the calling party hangs up:

6a. Cloud SIP UA receives a SIP BYE from the caller.

7a. The service sends a POST /callHungup callback to the application. The application responds with HTTPS 200 OK.

8a. Cloud SIP UA responds to the caller with SIP 200 OK.

If the application ends the call:

6b. The application calls the POST /hangupcall API. The service responds with HTTPS 200 OK.

7b. The service sends a SIP BYE to the caller.

8b. The caller responds with SIP 200 OK.

Sequence Diagram

sequenceDiagram participant Caller participant Cloud_SIP_UA participant App Caller->>Cloud_SIP_UA: SIP INVITE Cloud_SIP_UA->>Caller: SIP 100 Trying Cloud_SIP_UA->>App: /newRemoteCall (callback) App->>Cloud_SIP_UA: HTTP 200 OK App->>Cloud_SIP_UA: /remotecallringback Cloud_SIP_UA->>App: HTTP 200 OK Cloud_SIP_UA->>Caller: SIP 180 Ringing App->>Cloud_SIP_UA: /answerremotecall Cloud_SIP_UA->>App: HTTP 200 OK Cloud_SIP_UA->>Caller: SIP 200 OK Caller->>Cloud_SIP_UA: SIP ACK Caller<<-->>App: RTP Media alt Caller hangs up Caller->>Cloud_SIP_UA: SIP BYE Cloud_SIP_UA->>App: /callHungup App->>Cloud_SIP_UA: HTTP 200 OK Cloud_SIP_UA->>Caller: SIP 200 OK else App hangs up App->>Cloud_SIP_UA: /hangupcall Cloud_SIP_UA->>App: HTTP 200 OK Cloud_SIP_UA->>Caller: SIP BYE Caller->>Cloud_SIP_UA: SIP 200 OK end

For more details on the callback events and APIs used in this flow, see the Cloud SIP UA API documentation.

Example: Place a call

The following steps describe how a Cloud SIP UA device initiates an outbound call using the Cloud SIP UA Service:

  1. Initiate the call

    The customer application calls the POST /placeremotecall API, specifying the target SIP address using the destinationUri parameter. The service responds with HTTPS 200 OK.

  2. SIP INVITE is sent

    The Cloud SIP UA Service initiates a SIP INVITE to the destination SIP URI.

  3. Callee starts ringing

    Upon receiving a SIP 180 Ringing from the callee, the service sends a POST /callNotify callback with the event type "ringing". The application responds with HTTPS 200 OK.

  4. Callee answers

    When the call is answered, the service sends a POST /callAnswered callback to the application. The application responds with HTTPS 200 OK. RTP media is now exchanged based on the media settings provided in the original /placeremotecall request and the SIP 200 OK received from the callee.

Call Termination Scenarios

If the remote callee hangs up:

5a. Cloud SIP UA receives a SIP BYE from the callee.

6a. The service sends a POST /callHungup callback to the application. The application responds with HTTPS 200 OK.

7a. Cloud SIP UA responds with SIP 200 OK.

If the application ends the call:

5b. The application calls the POST /hangupcall API. The service responds with HTTPS 200 OK.

6b. The service sends a SIP BYE to the callee.

7b. The callee responds with SIP 200 OK.

Sequence Diagram

sequenceDiagram participant App participant Cloud_SIP_UA participant Callee App->>Cloud_SIP_UA: /placeremotecall Cloud_SIP_UA->>App: HTTP 200 OK Cloud_SIP_UA->>Callee: SIP INVITE Callee->>Cloud_SIP_UA: SIP 180 Ringing Cloud_SIP_UA->>App: /callNotify (event: ringing) App->>Cloud_SIP_UA: HTTP 200 OK Callee->>Cloud_SIP_UA: SIP 200 OK Cloud_SIP_UA->>App: /callAnswered App->>Cloud_SIP_UA: HTTP 200 OK Cloud_SIP_UA->>Callee: SIP ACK App<<-->>Callee: RTP Media alt Callee hangs up Callee->>Cloud_SIP_UA: SIP BYE Cloud_SIP_UA->>App: /callHungup App->>Cloud_SIP_UA: HTTP 200 OK Cloud_SIP_UA->>Callee: SIP 200 OK else App hangs up App->>Cloud_SIP_UA: /hangupcall Cloud_SIP_UA->>App: HTTP 200 OK Cloud_SIP_UA->>Callee: SIP BYE Callee->>Cloud_SIP_UA: SIP 200 OK end

For details on API usage and callbacks, refer to the Cloud SIP UA API documentation.