API docs by Redocly

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}/sendremotecallringback

POST

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

Authorizations:
sigv4
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

Request samples

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

Response samples

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

/mediaservice/{domain}/sendremotecallringback

OPTIONS
path Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{ }

/mediaservice/{domain}/hangupcall

POST

Terminate ongoing call handled by cloud SIP user agent.

Authorizations:
sigv4
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

Request samples

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

Response samples

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

/mediaservice/{domain}/hangupcall

OPTIONS
path Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{ }

/mediaservice/{domain}/answerremotecall

POST

Answer an incoming remote call indicated by the newRemoteCall callback.

Authorizations:
sigv4
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.

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.

Responses

Request samples

Content type
application/json
{
  • "codec": "string",
  • "sessionReferenceId": "string",
  • "replyId": "string",
  • "receivePort": 0,
  • "receiveIp": "string"
}

Response samples

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

/mediaservice/{domain}/answerremotecall

OPTIONS
path Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{ }

/mediaservice/{domain}/placeremotecall

POST

Send SIP invite request originating from cloud SIP user agent.

Authorizations:
sigv4
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.

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.

callbackBaseUrl
string

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

Responses

Request samples

Content type
application/json
{
  • "codec": "string",
  • "sessionReferenceId": "string",
  • "destinationUri": "string",
  • "sourceUser": "string",
  • "receivePort": 0,
  • "receiveIp": "string",
  • "callbackBaseUrl": "string"
}

Response samples

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

/mediaservice/{domain}/placeremotecall

OPTIONS
path Parameters
domain
required
string

Responses

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.

siteId
string

An identifier for the specific site running the service. Only used in the hybrid environment

httpTransactionId
string

An unique identifier for the http transaction.

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",
  • "siteId": "hy",
  • "httpTransactionId": "6f486ab0-fa96-11ef-a5b0-5d34730683ab"
}

/callFailed

POST
Request Body schema: application/json

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

callId
string

The SIP Call-Id for the call that failed.

status
number

SIP status code of the response from the remote side.

reason
string

SIP reason phrase of the response from the remote side.

sessionReferenceId
string

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

Responses

Request samples

Content type
application/json
{
  • "callId": "nfdfsij82893kn",
  • "status": 403,
  • "reason": "Forbidden",
  • "sessionReferenceId": 20000
}

/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

An identifier for the specific site running the service. Only used in the hybrid environment

httpTransactionId
string

An unique identifier for the http transaction.

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": "hy",
  • "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

Responses

Request samples

Content type
application/json
{
  • "callId": "nfdfsij82893kn",
  • "sessionReferenceId": 20000
}

/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.

replyId
string

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

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

Responses

Request samples

Content type
application/json
{
  • "replyId": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkb21...",
  • "callId": "nfdfsij82893kn",
  • "codec": "PCMA",
  • "destinationUri": "sip:user@domain.com",
  • "sourceUser": 1234567,
  • "remoteRtpIp": "10.2.30.12",
  • "remoteRtpPort": 20000
}

Response samples

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