Cloud SIP UA

Download OpenAPI specification:Download

cloudsipua_0

The Cloud SIP UA (User Agent) API enables thin devices that do not fit a full SIP-stack implementation to connect with SIP-based communication systems through REST APIs and real-time callbacks that mirror SIP signaling.

Cloud SIP UA Endpoints

Base url: https://api.prod-eu-north-1.iotcomms.io

/mediaservice/{domain}/answerremotecalljwt

POST

Answer an incoming remote call indicated by the newRemoteCall callback.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
Request Body schema: application/json
required
codec
string

Specifies the voice codec to be requested from the remote side for the call. Allowed values are PCMA or PCMU

sessionReferenceId
string

This is an optional property to be set by the system calling the API. If this is set the value will be copied into callback requests related to the session originating from the API call.

telephoneEventPayloadType
number

The payload type used for conveying telephone events. Please read RFC2833.

replyId
string

Set this propery to the replyId received from the newRemoteCall callback to answer the call.

receivePort
number

Specifies the RTP port where the remote side shall send media.

receiveIp
string

Specifies the IP address that the remote side shall send media to.

Array of objects

List of cryptos

Array
suite
string

The SRTP crypto suite that defines the exact cipher, key length and authentication algorithm that will protect the RTP/RTCP packets. Examples include AES_CM_128_HMAC_SHA1_80 (AES-CTR 128-bit encryption + 80-bit HMAC-SHA-1 authentication) and F8_128_HMAC_SHA1_80. The suite string is negotiated in offer/answer. Referenced as crypto-suite in RFC4568

id
number

A decimal label that uniquely identifies this crypto attribute inside one media description. During offer/answer the answerer echoes the chosen id so both sides know which set of keys/suite was accepted. Must be unique within the m-line and MUST NOT contain leading zeros. Referenced as tag in the RFC4568.

config
string

The key-params field provides one or more sets of keying material for the crypto-suite in question. The field consists of a method indicator followed by a colon. <key-method> : <key-info>. Only key-method inline is supported. See RFC4568.

Responses

Response Headers
Access-Control-Allow-Origin
string
Response Schema: application/json
success
boolean

Indicates if the API call was successful or not

Request samples

Content type
application/json
{
  • "codec": "string",
  • "sessionReferenceId": "string",
  • "telephoneEventPayloadType": 0,
  • "replyId": "string",
  • "receivePort": 0,
  • "receiveIp": "string",
  • "crypto": [
    • {
      • "suite": "string",
      • "id": 0,
      • "config": "string"
      }
    ]
}

Response samples

Content type
application/json
{
  • "success": true
}

/mediaservice/{domain}/answerremotecalljwt

OPTIONS
path Parameters
domain
required
string

Responses

Response Headers
Access-Control-Allow-Origin
string
Access-Control-Allow-Methods
string
Access-Control-Allow-Headers
string
Response Schema: application/json
object (Empty Schema)

Response samples

Content type
application/json
{ }

/mediaservice/{domain}/hangupcalljwt

POST

Terminate ongoing call handled by cloud SIP user agent. If the call has not yet been answered a busy will be sent otherwise the call will be hungup.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
Request Body schema: application/json
required
replyId
string

Set this propery to the replyId received from the callAnswered callback to hang up the call.

Responses

Response Headers
Access-Control-Allow-Origin
string
Response Schema: application/json
success
boolean

Indicates if the API call was successful or not

Request samples

Content type
application/json
{
  • "replyId": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

/mediaservice/{domain}/hangupcalljwt

OPTIONS
path Parameters
domain
required
string

Responses

Response Headers
Access-Control-Allow-Origin
string
Access-Control-Allow-Methods
string
Access-Control-Allow-Headers
string
Response Schema: application/json
object (Empty Schema)

Response samples

Content type
application/json
{ }

/mediaservice/{domain}/placeremotecalljwt

POST

Send SIP invite request originating from cloud SIP user agent.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
Request Body schema: application/json
required
codec
string

Specifies the voice codec to be requested from the remote side for the call. Allowed values are PCMA,PCMU or GSM

sessionReferenceId
string

This is an optional property to be set by the system calling the API. If this is set the value will be copied into callback requests related to the session originating from the API call.

destinationUri
string

SIP URI for the remote side of the call to be set up by the cloud SIP user agent.

telephoneEventPayloadType
number

The payload type used for conveying telephone events. Please read RFC2833.

sourceUser
string

Specifies the user part of the from: URI for the call triggered. This will be indicated as the calling party number for the remote side.

receivePort
number

Specifies the RTP port where the remote side shall send media.

receiveIp
string

Specifies the IP address that the remote side shall send media to.

Array of objects

List of cryptos

Array
suite
string

The SRTP crypto suite that defines the exact cipher, key length and authentication algorithm that will protect the RTP/RTCP packets. Examples include AES_CM_128_HMAC_SHA1_80 (AES-CTR 128-bit encryption + 80-bit HMAC-SHA-1 authentication) and F8_128_HMAC_SHA1_80. The suite string is negotiated in offer/answer. Referenced as crypto-suite in RFC4568

id
number

A decimal label that uniquely identifies this crypto attribute inside one media description. During offer/answer the answerer echoes the chosen id so both sides know which set of keys/suite was accepted. Must be unique within the m-line and MUST NOT contain leading zeros. Referenced as tag in the RFC4568.

config
string

The key-params field provides one or more sets of keying material for the crypto-suite in question. The field consists of a method indicator followed by a colon. <key-method> : <key-info>. Only key-method inline is supported. See RFC4568.

callbackBaseUrl
string

Base URL where callback notifications for the call triggered by the API is sent.

Responses

Response Headers
Access-Control-Allow-Origin
string
Response Schema: application/json
success
boolean

Indicates if the API call was successful or not

Request samples

Content type
application/json
{
  • "codec": "string",
  • "sessionReferenceId": "string",
  • "destinationUri": "string",
  • "telephoneEventPayloadType": 0,
  • "sourceUser": "string",
  • "receivePort": 0,
  • "receiveIp": "string",
  • "crypto": [
    • {
      • "suite": "string",
      • "id": 0,
      • "config": "string"
      }
    ],
  • "callbackBaseUrl": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

/mediaservice/{domain}/placeremotecalljwt

OPTIONS
path Parameters
domain
required
string

Responses

Response Headers
Access-Control-Allow-Origin
string
Access-Control-Allow-Methods
string
Access-Control-Allow-Headers
string
Response Schema: application/json
object (Empty Schema)

Response samples

Content type
application/json
{ }

/mediaservice/{domain}/sendremotecallringbackjwt

POST

Send ringback progress response for the call notified in the newRemoteCall callback.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
Request Body schema: application/json
required
replyId
string

Set this propery to the replyId received from the newRemoteCall callback to answer the call.

Responses

Response Headers
Access-Control-Allow-Origin
string
Response Schema: application/json
success
boolean

Indicates if the API call was successful or not

Request samples

Content type
application/json
{
  • "replyId": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

/mediaservice/{domain}/sendremotecallringbackjwt

OPTIONS
path Parameters
domain
required
string

Responses

Response Headers
Access-Control-Allow-Origin
string
Access-Control-Allow-Methods
string
Access-Control-Allow-Headers
string
Response Schema: application/json
object (Empty Schema)

Response samples

Content type
application/json
{ }

Cloud SIP UA Callbacks

/callAnswered

POST
Request Body schema: application/json

Event sent when mediaservice call is connected to a pre configured callback endpoint

callingPartyNumber
string

SIP user part of calling party in the call that has been connected

callerParticipantId
string

participantId of calling party in the call that has been connected

calleeParticipantId
string

participantId of called party in the call that has been connected

remotePartyNumber
string

SIP user part of called party in the call that has been connected

connectionId
string

The id for the connection that the participants in the call belongs to

callingPartyExpires
number

If the calling party SIP call leg has a session expiration the value is indicated here

calledPartyExpires
number

If the called party SIP call leg has a session expiration the value is indicated here

codec
string
Enum: "PCMU" "PCMA" "GSM"

This field is only present if the httpcall action was used to connect the participants. The codec received in SDP to be used by the device behind CloudUA to send media to

monitoringParticipant
boolean

Indicates if the event belong to a call monitoring leg

remoteRtpIp
string

This field is only applicable and mandatory for the httpcall action. The IP address received in SDP to be used by the device behind CloudUA to send media to

remoteRtpPort
string

This field is only applicable and mandatory for the httpcall action. The IP port received in SDP to be used by the device behind CloudUA to send media to

replyId
string

The replyId property must be copied into subsequent requests related to this call.

sessionReferenceId
object

If this value has been set in invoking API call the value is copied to subsequent callback requests

traceId
string

traceId is a unique identifier for an entire call that may span multiple sessions. Makes it easier to track calls through the platform.

httpTransactionId
string

An unique identifier for the http transaction.

siteId
string

The hybrid site id where the callback request originates from. Only present in hybrid deployments

siteBaseUrl
string

This property is present only in hybrid deployments and it indicates the base URL for API calls for site specific API calls for further actions related to the callback.

Responses

Request samples

Content type
application/json
{
  • "callingPartyNumber": 46890510,
  • "callerParticipantId": "d93f0370-c787-11eb-a47c-c9c4e460ef16",
  • "calleeParticipantId": "da9cbeb0-c787-11eb-a47c-c9c4e460ef16",
  • "remotePartyNumber": 46890200,
  • "connectionId": "da9ce5c0-c787-11eb-a47c-c9c4e460ef16",
  • "callingPartyExpires": 600,
  • "calledPartyExpires": 600,
  • "codec": "GSM",
  • "monitoringParticipant": false,
  • "remoteRtpIp": "10.0.0.2",
  • "remoteRtpPort": 45000,
  • "replyId": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkb21...",
  • "sessionReferenceId": { },
  • "traceId": "d9b15290-fa96-11ef-a9c8-631ff62a0f63",
  • "httpTransactionId": "6f486ab0-fa96-11ef-a5b0-5d34730683ab",
  • "siteId": "siteA",
  • "siteBaseUrl": "https://api.&lt;siteId&gt;.&lt;stage&gt;.iotcomms.io"
}

/callFailed

POST
Request Body schema: application/json

Event sent when call if the cloud SIP user agent fails to set up the call.

sipCallId
string

The SIP Call-Id for the call that failed.

sipStatus
number

SIP status code of the response from the remote side.

sipReason
string

The reason text as sent from remote side.

errorDescr
string

The reason text as sent from remote side.

sessionReferenceId
string

If this value has been set in invoking API call the value is copied to subsequent callback requests

sessionId
string

The sessionId identifies the session

ivrServer
string

The ivrServer is the IP address of the node that sends the command

participantId
string

Used as parameter for the connect action to tell which other participant the participant related to the callEvent sent should be connected with.

domain
string

The domain that triggered the alarm event

traceId
string

traceId is a unique identifier for an entire call that may span multiple sessions. Makes it easier to track calls through the platform.

httpTransactionId
string

An unique identifier for the http transaction.

Responses

Request samples

Content type
application/json
{
  • "sipCallId": "nfdfsij82893kn",
  • "sipStatus": 403,
  • "sipReason": "Busy Here",
  • "errorDescr": "Busy Here",
  • "sessionReferenceId": 20000,
  • "sessionId": "9bb07660-c747-11ea-afa0-bd07728b88b7",
  • "ivrServer": "127.0.0.1",
  • "participantId": "c2af21a1-e90f-11ea-9564-1f1d01c9e7c9",
  • "domain": "customer.prod-eu-north-1.iotcomms.io",
  • "traceId": "d9b15290-fa96-11ef-a9c8-631ff62a0f63",
  • "httpTransactionId": "6f486ab0-fa96-11ef-a5b0-5d34730683ab"
}

/callHungup

POST
Request Body schema: application/json

Event sent when the call served by the cloud SIP user agent has been hung up.

callId
string

The SIP Call-Id for the call that was disconnected.

sessionReferenceId
string

If this value has been set in invoking API call the value is copied to subsequent callback requests

destinationUri
string

The SIP request URI of the incoming call.

sourceUser
string

The user part of the SIP from: header of the incoming call

Responses

Request samples

Content type
application/json
{
  • "callId": "nfdfsij82893kn",
  • "sessionReferenceId": 20000,
  • "destinationUri": "sip:user@domain.com",
  • "sourceUser": 1234567
}

/callNotify

POST
Request Body schema: application/json

Notifications sent by the IVR to indicate call events.

string or string or string
Enum: "ringing" "reInvite" "update"
One of
string
Enum: "ringing" "reInvite" "update"

'ringing' indicates that ringing response has been received

monitoringParticipant
boolean

Indicates if the event belong to a call monitoring leg

participantId
string

Unique id for the participant tha the event is associated with

sessionId
string

The sessionId identifies the session

sessionReferenceId
string

If this value has been set in invoking API call the value is copied to subsequent callback requests

user
string

SIP user part of the participant that caused the event to be sent

remoteUser
string

SIP user part for the participant of the remote side of the connection for the participant that caused the event to be sent

remoteParticipantId
string

Unique of for the participant of the remote side of the connection for the participant caused the event to be sent

sipCallId
string

The sipCallId is the corresponding value from SIP-Invite

ivrServer
string

The ivrServer is the IP address of the node that sends the command

traceId
string

traceId is a unique identifier for an entire call that may span multiple sessions. Makes it easier to track calls through the platform.

siteId
string

The hybrid site id where the callback request originates from. Only present in hybrid deployments

siteBaseUrl
string

This property is present only in hybrid deployments and it indicates the base URL for API calls for site specific API calls for further actions related to the callback.

Responses

Request samples

Content type
application/json
{
  • "event": "ringing",
  • "monitoringParticipant": false,
  • "participantId": "9bb07660-c747-11ea-afa0-bd07728b88b7",
  • "sessionId": "9bb07660-c747-11ea-afa0-bd07728b88b7",
  • "sessionReferenceId": 20000,
  • "user": "+46890510",
  • "remoteUser": "+46890200",
  • "remoteParticipantId": "da9cbeb0-c787-11eb-a47c-c9c4e460ef16",
  • "sipCallId": 5473001594892095000,
  • "ivrServer": "127.0.0.1",
  • "traceId": "d9b15290-fa96-11ef-a9c8-631ff62a0f63",
  • "siteId": "siteA",
  • "siteBaseUrl": "https://api.&lt;siteId&gt;.&lt;stage&gt;.iotcomms.io"
}

/newRemoteCall

POST
Request Body schema: application/json

Event sent when cloud SIP user agent has received a new incoming call. Use answerRemoteCall to answer it.

httpTransactionId
string

An unique identifier for the http transaction.

sessionId
string

The sessionId identifies the session

replyId
string

The replyId property must be copied into subsequent requests related to this call.

traceId
string

The traceId is conveyed throughout the service and can be provided in the initial API-call.

domain
string

The domain configured for the tenant triggering the event

ivrServer
string

The ivrServer is the IP address of the node that sends the callback

callId
string

The SIP Call-Id for the call that has been answered by the remote side

codec
string

The codec that the remote side want to receive.

destinationUri
string

The SIP request URI of the incoming call.

sourceUser
string

The user part of the SIP from: header of the incoming call

remoteRtpIp
string

The IP address that the remote side want to receive media on

remoteRtpPort
number

The RTP port that the remote side want to receive media on.

telephoneEventPayloadType
number

The payload type use by the remote end to send telephone events such as DTFM, hook flash and FAX tones.

Array of objects

List of cryptos

Array
id
number

A decimal label that uniquely identifies this crypto attribute inside one media description. During offer/answer the answerer echoes the chosen id so both sides know which set of keys/suite was accepted. Must be unique within the m-line and MUST NOT contain leading zeros. Referenced as tag in the RFC4568.

suite
string

The SRTP crypto suite that defines the exact cipher, key length and authentication algorithm that will protect the RTP/RTCP packets. Examples include AES_CM_128_HMAC_SHA1_80 (AES-CTR 128-bit encryption + 80-bit HMAC-SHA-1 authentication) and F8_128_HMAC_SHA1_80. The suite string is negotiated in offer/answer. Referenced as crypto-suite in RFC4568

config
string

The key-params field provides one or more sets of keying material for the crypto-suite in question. The field consists of a method indicator followed by a colon. key-method : key-info. Only key-method inline is supported. See RFC4568.

Responses

Response Schema: application/json
sessionReferenceId
string

If this is set the value will be copied into callback requests related to the session assiciated with the response.

Request samples

Content type
application/json
{
  • "httpTransactionId": "6f486ab0-fa96-11ef-a5b0-5d34730683ab",
  • "sessionId": "9bb07660-c747-11ea-afa0-bd07728b88b7",
  • "replyId": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkb21...",
  • "traceId": "9851cf70-1cc8-11ef-b3dd-9b598c1e38cf",
  • "domain": "customer.prod-eu-north-1.iotcomms.io",
  • "ivrServer": "127.0.0.1",
  • "callId": "nfdfsij82893kn",
  • "codec": "PCMA",
  • "destinationUri": "sip:user@domain.com",
  • "sourceUser": 1234567,
  • "remoteRtpIp": "10.2.30.12",
  • "remoteRtpPort": 20000,
  • "telephoneEventPayloadType": 101,
  • "crypto": [
    • {
      • "id": 0,
      • "suite": "string",
      • "config": "string"
      }
    ]
}

Response samples

Content type
application/json
{
  • "sessionReferenceId": "mySessionReference"
}