Mediaservice

Download OpenAPI specification:Download

mediaservice_0

The mediaservice API provides functionality to build the advanced interactive call flows where REST callbacks are triggered upon new incoming calls or changes in call state during ongoing calls. The REST endpoint allows interaction with the ongoing calls. It also provides functionality to play text to speech prompts, listen for DTMF tones and, record calls. It can also trigger outbound calls and connect the communication participants with each other.

Mediaservice API Endpoints

Base url: https://api.prod-eu-north-1.iotcomms.io/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.

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
}

/{domain}/answerremotecall

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
{ }

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

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

/{domain}/hangupcall

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

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
}

/{domain}/hangupcall

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
{ }

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

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

/{domain}/hangupparticipant

POST

Hang up call for a specified participant.

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

The id for the participant to be hung up.

replyId
string

Set this to the value of replyId receviced in the callNotify or callAnswered originating from the particpant or connection related to partcipant to be hung up.

sessionId
string

The id for the IVR session that executes the command.

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
{
  • "participantId": "string",
  • "replyId": "string",
  • "sessionId": "string"
}

Response samples

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

/{domain}/hangupparticipant

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
{ }

/{domain}/hangupremoteparticipant

POST

Hang up call for remote party of a specified participant.

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

The id for the participant for which it's remote party is to be hung up.

replyId
string

Set this to the value of replyId receviced in the callNotify or callEvent originating from the particpant or connection related to partcipant to be hung up.

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
{
  • "participantId": "string",
  • "replyId": "string"
}

Response samples

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

/{domain}/hangupremoteparticipant

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
{ }

/{domain}/interruptivrcommand

POST

Interrupt an ongoing IVR command and triggers a new /getIvrCommand request.

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

Set this to the value of replyId receviced in the getIvrCommand request that started the command to be interrupted.

sessionId
string

The id for the IVR session that executes the command.

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",
  • "sessionId": "string"
}

Response samples

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

/{domain}/interruptivrcommand

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
{ }

/{domain}/placeivrcall

POST

Trigger an outbound call from IVR service to destination provided in destAddr. When called party answers a callAnswered and getIvrCommand event is sent for further processing.

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

User part of from: header in the. Set this to the phone number or user id to be displayed for the remote party.

xHeaders
object

This property allow custom X- headers to be added to the SIP request of the call generated in case the action is set to call. It take an object of format {x-header1:val1, x-header2:val2} as value resulting in the SIP headers and values X-Header1: val1 and X-Header2: val2. To set multiple header values for same header pass an array : {x-header3: [val1,val2]}.

sessionReferenceId
object

Optional sessionReferenceId object that is copied into the sessionReferenceId property in subsequent callback requests for the session created.

sipDiversion
string

It defines which number should be placed in SIP-Diversion header if action is “call”. If this parameter is omitted then no SIP-Diversion header should be included in the SIP-INVITE.

displayName
string

If this property is set the value is set as display name in the the from: header of the SIP request for the outgoing IVR call

callerPrivacy
boolean

Indicates if the calling party number should be hidden in the call that is set up from the IVR as result of the placeivrcall API request.

contactParameters
object

This property allow custom URL parameters to be added to the contact: header of the call generated in case the action is set to call. It take an object of format {prop1:val1, prop2:val2} as value resulting in the URL parameters prop1=val1;prop2=val2 to be appended to the URL in contact: header.

sipDiversionParameters
object

An object of format {param:paramValue} which sets the header parameters for the diversion header

pHeaders
object

This property allow custom P- headers to be added to the SIP request of the call generated in case the action is set to call. It take an object of format {p-header1:val1, p-header2:val2} as value resulting in the SIP headers and values P-Header1: val1 and P-Header2: val2. To set multiple header values for same header pass an array : {p-header3: [val1,val2]}.

contactUserParameters
object

This property allow custom user parameters to be added to the contact: header of the call generated in case the action is set to call. It take an object of format {prop1:val1, prop2:val2} as value resulting in the user parameters prop1=val1;prop2=val2 to be appended to the user part of URL in contact: header.

destAddr
string

SIP URI pointing to the destination to be connected with the IVR service.

mediaserviceId
string

If this property is set the value is matched against the id property of the provisioned meddia server configurations. The matching configuration is used for the mediaserver session resulting to the API call. If this property is not passed configuration of the first provisioned mediaserver configuration will be used.

maxRingTime
number

Decimal number of seconds to wait for destination to answer the calls.

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
{
  • "sipFrom": "string",
  • "xHeaders": { },
  • "sessionReferenceId": { },
  • "sipDiversion": "string",
  • "displayName": "string",
  • "callerPrivacy": true,
  • "contactParameters": { },
  • "sipDiversionParameters": { },
  • "pHeaders": { },
  • "contactUserParameters": { },
  • "destAddr": "string",
  • "mediaserviceId": "string",
  • "maxRingTime": 0
}

Response samples

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

/{domain}/placeivrcall

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
{ }

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

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
}

/{domain}/placeremotecall

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
{ }

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

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

/{domain}/promptfile

GET

List recorded prompt files

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
query Parameters
next
string

Responses

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

If there are additional results to retrieve, this value can be passed with the next request to retrieve them. If it is null there are no additional results.

success
boolean

Indicates if the request was successful or not.

Array of objects

List of files currently stored.

Array
size
number

The size of the file in bytes.

name
string

The name of the file.

Response samples

Content type
application/json
{
  • "next": "string",
  • "success": true,
  • "files": [
    • {
      • "size": 0,
      • "name": "string"
      }
    ]
}

/{domain}/promptfile/{filename}

GET

Get recorded prompt file from IVR service

Authorizations:
jwtAuthorizer
path Parameters
filename
required
string
domain
required
string

Responses

Response Headers
Access-Control-Allow-Origin
string
Response Headers
Content-Type
string

/{domain}/promptfile/{filename}

PUT

Add or update recorded prompt file to IVR service

Authorizations:
jwtAuthorizer
path Parameters
filename
required
string
domain
required
string

Responses

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

Indicates if the API call was successful or not

Response samples

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

/{domain}/promptfile/{filename}

DELETE

Delete recorded prompt file from IVR service

Authorizations:
jwtAuthorizer
path Parameters
filename
required
string
domain
required
string

Responses

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

Indicates if the API call was successful or not

Response samples

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

/{domain}/promptfile/{filename}

OPTIONS
path Parameters
filename
required
string
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
{ }

/{domain}/promptfile/{filename}/move

POST

Move a prompt file to an external destination. After the file has been moved it will no longer exist in its original location.

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

The AWS region of the destination S3 bucket.

bucketName
required
string

The name of the destination S3 bucket.

kmsKey
string

Optional KMS key identifier for encrypting the destination object. The key must be configured to allow the following actions from our account: kms:Encrypt, kms:GenerateDataKey

objectKey
string

Optional destination object key in S3. Defaults to the prompt's current name.

type
required
string
Value: "s3"

The destination type. The supported options are:

  • s3: The destination is an S3 bucket. The bucket must be configured to allow the following actions from our account: s3:PutObject, s3:PutObjectAcl

Responses

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

Indicates if the request was successful or not.

Request samples

Content type
application/json
{
  • "bucketRegion": "string",
  • "bucketName": "string",
  • "kmsKey": "string",
  • "objectKey": "string",
  • "type": "s3"
}

Response samples

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

/{domain}/promptfile/{filename}/move

OPTIONS
path Parameters
filename
required
string
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
{ }

/{domain}/promptfile/{filename}/url

GET

Get recorded prompt file url from IVR service

Authorizations:
jwtAuthorizer
path Parameters
filename
required
string
domain
required
string

Responses

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

User readable string explainging why the operation failed. Only present when success is false.

success
boolean

Indicates if the request was successful or not.

error
string

The full error as provided by underlying system. Only present when success if false.

url
string

The pre-signed URL to be used to retrieve the actual file.It is valid for 15 minutes. Only present if success is true.

Response Headers
Content-Type
string

Response samples

Content type
application/json
{
  • "reason": "string",
  • "success": true,
  • "error": "string",
  • "url": "string"
}

/{domain}/promptfile/{filename}/url

OPTIONS
path Parameters
filename
required
string
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
{ }

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

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
}

/{domain}/sendremotecallringback

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
{ }

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

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

/{domain}/splitconnection

POST

Split an IVR connection into individual disconnected participants. A callEvent is triggered per perticipant to get information on how to proceed.

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

Set this to the value of replyId received in the callAnswered callback for the connection

connectionId
string

The connectionId for connection to be split. This is provided in the callAnswered event that is sent when a connection is established.

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",
  • "connectionId": "string"
}

Response samples

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

/{domain}/splitconnection

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
{ }

/{domain}/startrecording

POST

Start call recording for an already established call connection.

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

The file name that will be used when the call recording is uploaded to the prompt storage.

replyId
string

Set this to the value of replyId received in the callAnswered callback for the connection.

connectionId
string

The connectionId for connection to be recorded. connectionId is provided in the callAnswered event that is sent when a connection is established.

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
{
  • "recordingFileName": "string",
  • "replyId": "string",
  • "connectionId": "string"
}

Response samples

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

/{domain}/startrecording

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
{ }

/{domain}/stoprecording

POST

Stop call recording for an already established call connection that is being recorded. This will trigger the recording file to be uploaded to prompt storage.

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

Set this to the value of replyId received in the callAnswered callback for the connection.

connectionId
string

The connectionId for connection to stop recording for. connectionId is provided in the callAnswered event that is sent when a connection is established.

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",
  • "connectionId": "string"
}

Response samples

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

/{domain}/stoprecording

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 API 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"
}

/callEvent

POST
Request Body schema: application/json

Indicates that call related event on a connection occurred. It is either sent in case one party hang up the call or the /splitconnection API endpoint is called. If a party is hanging up the action provided in the response is applied on the remaining party in the connection. For /splitconnection one event is sent per connection participant and action applies for the participant.

connectionId
string

Unique id of the connection that the participant that caused the event to be sent belonged to

domain
string

The domain configured for the tenant triggering the event

event
string
Enum: "callingPartyDrop" "calledPartyDrop" "callingPartyFailure" "calledPartyFailure" "callerConnectionSplit" "calleeConnectionSplit"

The type of event that triggered the /callEvent to be sent

ivrServer
string

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

participantId
string

Unique id 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

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

sessionId
string

The sessionId identifies the current session

user
string

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

sessionReferenceId
string

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

sipResponseCode
number

The SIP status code that was received.

errorDescr
string

A descriptive text that indicate what has caused the call setup failure.

sipReason
string

The SIP Reason header as received from remote party.

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

Response Schema: application/json
action
string

Action defines what IVR should do with the participants in a connection. It can take four values:

  • call: means the remaining party will get connected with the destination specified in destAddr property
  • httpcall: means that the remaining party will be connected with a CloudUA destination as specified with the receiveIp, receivePort and codec properties
  • ivr: means that participant will get connected with IVR service that will answer call an issue getIvrCommand request
  • connect: means that the participant will get connected with another participant specified with the participantId property.
  • drop: means that call will get dropped
callerPrivacy
boolean

Indicates if the calling party number should be hidden in the call that is set up from the IVR as result of the call action.

callRecording
boolean

Indicates if the call connected should be recorded. Media will be connected through the mediaservice and once the call is completed the recorded file is uploaded to the prompt storage.

contactParameters
object

This property allow custom URL parameters to be added to the contact: header of the call generated in case the action is set to call. It take an object of format {"prop1":"val1", "prop2":"val2"} as value resulting in the URL parameters prop1=val1;prop2=val2 to be appended to the contact: header.

contactUserParameters
object

This property allow custom user parameters to be added to the user part of URL in contact: header of the call generated in case the action is set to call. It take an object of format {"prop1":"val1", "prop2":"val2"} as value resulting in the URL parameters prop1=val1;prop2=val2 to be appended to the user part of the URL in contact: header.

string or Array of objects
One of
string

sip: URI to the destination to be called

displayName
string

If this property is set the value is set as display name in the the from: header of the SIP request in the case the action property is set to call

dropCode
string
Enum: "busy" "error" "numberNotFound" "numberNotActive" "dropNoMsg" "temporarilyUnavailable"

Setting a dropCode for action drop in a callEvent response will trigger a SIP Bye request to the remaining participant in the connection, where the reason header is set based on the dropCode value. In case of a callEvent triggered during call set up where ringbackTone is set to remoteGenerated is will send a final response matching the dropCode value in case the SIP call has not been connected.

object

Indicates if a greeting phrases should be played to participants before they are connected with each other.

playMode
string
Enum: "calleeFirst" "calleeConnected"

'calleeFirst' means the callee's prompt is played first, then caller's. 'calleeConnected' means parallel playback, i.e. caller prompt is played as soon as callee leg is connected.

object

Phrases to be played for the calling party.

phrases
Array of objects
object

Phrases to be played for the called party.

phrases
Array of objects
maxRingTime
number

Decimal number of seconds to wait for destination to answer the calls. This value is used in case no per-destination specific value is set

monitorDestAddr
string

This property is used in combination with call action in the response. When set it and the call between the two parties is connected it will automatically set up a second call to the SIP address provided in the monitorDestAddr property, the monitoring leg. This monitoring leg will provide a one way media stream containing the voice of the two connected parties. This function is typically used when developing contact center monitoring or analytics functions. Call setup progress for the call monitoring leg is reported in callNotify callback events which have the monitoringParticipant property set to true. Once the call monitoring leg have been answered a callAnswered callback event is sent having the monitoringParticipant property set to true. The connectionId and participantId property of the callAnswered callback event may be used for subsequent API calls, such as /hangupparticipant

monitorPHeaders
object

By default the P-headers are copied from the call to be monitored. This property allow custom P-headers to be added to the SIP request of the monitor call generated in case monitorDestAddr is set. It take an object of format {"x-header1":"val1", "x-header2":"val2"} as value resulting in the SIP headers and values X-Header1: val1 and X-Header2: val2. To set multiple header values for same header pass an array : {"x-header3": ["val1","val2"]}. To remove a X-header, set the value to null

monitorXHeaders
object

By default the X-headers are copied from the call to be monitored. This property allow custom X-headers to be added to the SIP request of the monitor call generated in case monitorDestAddr is set. It take an object of format {"p-header1":"val1", "p-header2":"val2"} as value resulting in the SIP headers and values P-Header1: val1 and P-Header2: val2. To set multiple header values for same header pass an array : {"p-header3": ["val1","val2"]}. To remove a P-header, set the value to null

pHeaders
object

This property allow custom P- headers to be added to the SIP request of the call generated in case the action is set to call. It take an object of format {"p-header1":"val1", "p-header2":"val2"} as value resulting in the SIP headers and values P-Header1: val1 and P-Header2: val2. To set multiple header values for same header pass an array : {"p-header3": ["val1","val2"]}.

ringbackTone
string

It defines which ringback tone should be played for calling party if action is “call”: &quot;default&quot; means that standard ringback tone should be played on inbound leg until outbound leg is answered, &quot;silent&quot; means that silence should be played on inbound leg until outbound leg is answered

recordingFileName
string

The call recording filename used when uploading the recording to the prompt storage

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.

sessionReferenceId
object

Object that is retained for the session and passed in subsequent requests

sipDiversion
string

It defines which number should be placed in SIP-Diversion header if action is “call”. If this parameter is omitted then no SIP-Diversion header should be included in the SIP-INVITE

sipDiversionParameters
object

An object of format {param:paramValue} which sets the header parameters for the diversion header

sipFrom
string

It defines which number should be placed in SIP-From header if action is “call”. If this parameter is omitted then number in SIP-From header should be copied from the SIP-From header in the inbound leg

sipPAI
string

It defines which number should be placed in SIP-PAI header if action is “call”. If this parameter is omitted then no SIP-PAI header should be included in the SIP-INVITE

sipRPID
string

It defines which number should be placed in SIP-RemotePartyId header if action is “call”. If this parameter is omitted then no SIP-RPID header should be included in the SIP-INVITE

sipTo
string

It defines which number should be placed in SIP-To header if action is “call”. If this parameter is omitted then cNumber should be placed in To header if action is “call”

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

This field is only applicable and mandatory for the httpcall action. The codec to be set in SDP to be received by the device behind CloudUA

receiveIp
string

This field is only applicable and mandatory for the httpcall action. The IP address that the device behind CloudUA want to receive media at

receivePort
string

This field is only applicable and mandatory for the httpcall action. The IP port that the device behind CloudUA want to receive media at

xHeaders
object

This property allow custom X- headers to be added to the SIP request of the call generated in case the action is set to call. It take an object of format {"x-header1":"val1", "x-header2":"val2"} as value resulting in the SIP headers and values X-Header1: val1 and X-Header2: val2. To set multiple header values for same header pass an array : {"x-header3": ["val1","val2"]}.

copyHeaders
Array of strings

This property is set to an array that contains the names of SIP headers starting with either the prefix P- or X- to be copied.

monitorSipFrom
string

It defines which number should be placed in SIP-From header and PAI header in the call monitoring call if action is “call” and “monitorDestAddr“ is set. If this parameter is omitted then number in SIP-From header of the monitoring call should be copied from the SIP-From header in the inbound leg

Request samples

Content type
application/json
{
  • "connectionId": "da5cbeb0-c787-11eb-a47c-c9c4e460ef16",
  • "domain": "customer.prod-eu-north-1.iotcomms.io",
  • "event": "calledPartyDrop",
  • "ivrServer": "127.0.0.1",
  • "participantId": "da9cbeb0-c787-11eb-a47c-c9c4e460ef16",
  • "remoteParticipantId": "da9cbeb0-c787-11eb-a47c-c9c4e460ef16",
  • "remoteUser": "+46890200",
  • "sessionId": "9bb07660-c747-11ea-afa0-bd07728b88b7",
  • "user": "+46890510",
  • "sessionReferenceId": 20000,
  • "sipResponseCode": 486,
  • "errorDescr": "Request cancelled",
  • "sipReason": "SIP ;cause=200 ;text=Call completed elsewhere",
  • "siteId": "siteA",
  • "siteBaseUrl": "https://api.&lt;siteId&gt;.&lt;stage&gt;.iotcomms.io"
}

Response samples

Content type
application/json
{
  • "action": "drop",
  • "callerPrivacy": true,
  • "callRecording": true,
  • "contactParameters": { },
  • "contactUserParameters": { },
  • "destAddr": "string",
  • "displayName": "Donald Duck",
  • "dropCode": "busy",
  • "greeting": {
    • "playMode": "calleeFirst",
    • "caller": {
      • "phrases": [
        • { }
        ]
      },
    • "callee": {
      • "phrases": [
        • { }
        ]
      }
    },
  • "maxRingTime": 2,
  • "monitorDestAddr": "sip:monitor@domain",
  • "monitorPHeaders": { },
  • "monitorXHeaders": { },
  • "pHeaders": { },
  • "ringbackTone": "default",
  • "recordingFileName": "filename.mp3",
  • "participantId": "c2af21a1-e90f-11ea-9564-1f1d01c9e7c9",
  • "sessionReferenceId": { },
  • "sipDiversion": 123456,
  • "sipDiversionParameters": { },
  • "sipFrom": "caller",
  • "sipPAI": "caller",
  • "sipRPID": 123456,
  • "sipTo": "callee",
  • "codec": "GSM",
  • "receiveIp": "10.0.0.1",
  • "receivePort": 30000,
  • "xHeaders": { },
  • "copyHeaders": [
    • "string"
    ],
  • "monitorSipFrom": "monitor"
}

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

/getCallIdentifier

POST
Request Body schema: application/json

Get call identifier from SN.

sessionId
string

The sessionId identifies the current session

calledParty
string

The calledParty is the complete user part (typically phonenumber) from the SIP-URI

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

Response Schema: application/json
sessionId
string

The sessionId identifies the current session

object
foo
integer
bar
integer

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "sessionId": "9bb07660-c747-11ea-afa0-bd07728b88b7",
  • "sessionReferenceId": {
    • "foo": 1,
    • "bar": 2
    }
}

/getIvrCommand

POST
Request Body schema: application/json

Requests a new IVR command from SN

sessionId
string

The sessionId identifies the session

sessionReferenceId
string

Uniquely identifies the call in the remote system

ivrServer
string

The IP address of the IVR node originating the request

dtmfBuffer
string

Holds the received DTMF digits in the buffer since last flushed. dtmfBuffer may be encrypted according to instructions in last response to getIvrCommand. If there are no DTMF in buffer then this parameter could be omitted

object
dtmfMatch
string

Holds the matched digits as a result of dtmf property of command. Terminationkey is excluded from match. If encryption is enabled it holds the encrypted data.

reason
string

Indicates what triggered the match. One of the values:

  • terminationKey
  • maxDigits
  • firstTimeout
  • betweenTimeout
matchedTerminationKey
string

This propery is present in case the reason was terminationKey. It then contain which termination key that matched.

encryption
object

If encryption was enabled and the DTMF encryption was sucessful this property is present indicating which encryption type that was and type specific information.

replyId
string

String to be copied in subsequent requests to the service. Also included in the 200 response

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

Response Schema: application/json
sessionId
string

The sessionId identifies the session

object
foo
integer
bar
integer
object
flush
boolean

If DTMF buffer should be cleared before playing phrases

object or object or object

If encryption property is passed with this configuration the mathced DTMF digits will not be sent in clear. The type property determines how to encrypt the DTMF input.

One of
type
required
string
Value: "md5"

The value md5 is passed to hash the DTMF input using a md5 hash.

salt
required
string

Optional salt string to be added to the DTMF input. The salt is added AFTER the matched DTMF string. (dtmfMatch+salt)

maxDigits
integer

Max number of DTMF-digits. If IVR get max number of digits then IVR should make a new getIvrCommand request with all received DTMF-digits

firstTimeout
number

Max number of seconds to receive first DTMF-digit. If this timer timed out before receiving any DTMF-digit then IVR should make a new getIvrCommand request with dtmfTimeout=true. Then timer starts when all the phrases in the phrases-array of IVR command has been played or in the case of a record phrase type it starts when recording starts.

betweenTimeout
number

Max number of seconds between DTMF-inputs. If this timer timed out before receiving next DTMF-digit then IVR should make a new getIvrCommand request with all received DTMF-digits

string or Array of strings
One of
string

DTMF-digit that should terminate DTMF-input. If IVR receive a terminationKey then IVR should make a new getIvrCommand request with all received DTMF-digits until match in the request.

Array of objects

List of files to be played or text to be played after translating via TTS

Array
format
string

The type of phrase to be played

Type Notes
awstts Synthesize speech using AWS Polly
googletts Synthesize speech using Google TTS
url Fetch mp3 file from URL
file Fetch uploaded prompt file
beep Plays a short beep
record Starts a recording
region
string
Enum: "eu-west-1" "eu-north-1" "us-east-1" "eu-central-1"

The region in where the text-to-speech synthesis will take place. Only used for awsTTSParameters. If region is Check the AWS Polly documentation for valid combinations of region, Engine, Voice, and LanguageCode.

awsTTSParameters
object

Parameters passed on to AWS Polly. Please see the AWS Polly documentation for details. You are able to specify which AWS region to use for text-to-speech synthesis using the region parameter.

googleTTSParameters
object

Parameters passed on to Googles API for synthesized speech. Only applicable for the 'googletts' phrase type

cacheTimeToLive
string

The duration for how long a downloaded phrase will be cached. Only applicable for the phrase types 'url', 'awstts', and 'googletts'.

Enum Days
DAY 1
WEEK 7
MONTH 30
QUARTER 91
HALF-YEAR 182
refreshCache
boolean

Instructs the IVR ignore the cache and obtain a new copy of the specified phrase. Only applicable for the 'url' & 'file' phrase types

fileName
string

Unique name of the prompt file if format is file or record. Name will not include filename extension

object

If background prompt should be played after phrases listed above has been played and between commands. Background prompt ends when IVR session is completed wiht hangup:true

fileName
string

Unique name of the prompt as used when uploaded using the promptfile API. File will be played in background of the call after or between phrases has been played.

url
string

URL pointing to MP3 file to be played in background of the call after or between phrases has been played.

repeatPause
number

The background prompt is automatically repeated. Set this property with a number if seconds to add silence period between repeats.

stop
boolean

Set this property to stop playout of a running backgroundPrompt. Must not be used in combination with url or fileName property.

bargeIn
string

If phrase should be interrupted if a DTMF match is detected during playout.

Enum Notes
never Never interrupt phrases
current Interrupt the currently playing phrase
all Interrupt all phrases for the current IVR command
recordedCallback
boolean

If true, the IVR will send a fileRecorded callback when a file has been recorded

hangup
boolean

If true, the IVR will hang up the current call when the phrases have been played out

getIVRCommandAfter
number

Specifies after how many seconds after last prompt a new getIvrCommand request will be sent. If backgroundPrompt is defined then it will be played during this period. If no backgroundPrompt is defined then it will be silent during this period

replyId
string

String to be copied to subsequent requests related to the command

Request samples

Content type
application/json
{
  • "sessionId": "9bb07660-c747-11ea-afa0-bd07728b88b7",
  • "sessionReferenceId": null,
  • "ivrServer": null,
  • "dtmfBuffer": null,
  • "dtmfParams": {
    • "dtmfMatch": "12",
    • "reason": "terminationKey",
    • "matchedTerminationKey": "#",
    • "encryption": { }
    },
  • "replyId": null,
  • "siteId": "siteA",
  • "siteBaseUrl": "https://api.&lt;siteId&gt;.&lt;stage&gt;.iotcomms.io"
}

Response samples

Content type
application/json
{
  • "sessionId": "9bb07660-c747-11ea-afa0-bd07728b88b7",
  • "sessionReferenceId": {
    • "foo": 1,
    • "bar": 2
    },
  • "dtmf": {
    • "flush": true,
    • "encryption": {
      • "type": "md5",
      • "salt": "string"
      },
    • "maxDigits": 10,
    • "firstTimeout": 30,
    • "betweenTimeout": 3,
    • "terminationKey": "string"
    },
  • "phrases": [
    • {
      • "format": "awstts",
      • "region": "eu-west-1",
      • "awsTTSParameters": null,
      • "googleTTSParameters": null,
      • "cacheTimeToLive": "WEEK",
      • "refreshCache": true,
      • "fileName": null
      }
    ],
  • "backgroundPrompt": {
    • "fileName": "string",
    • "url": "string",
    • "repeatPause": 0,
    • "stop": true
    },
  • "bargeIn": "current",
  • "recordedCallback": true,
  • "hangup": true,
  • "getIVRCommandAfter": 0,
  • "replyId": "string"
}

/newCall

POST
Request Body schema: application/json

Indicates that a new call has been received by IVR in case IN is not used. Response indicate if call should be connected to IVR, transferred elsewhere or terminated.

sessionId
string

The sessionId identifies the current session

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

callingPartyPrivacy
string

The callingPartyPrivacy tells if aNumber is “public” or “secret”

callingParty
string

The value of the callingParty property is the user part of SIP URI in P-Asserted identity header of incoming SIP request or if this header is not present it is retrieved from the from: header.

displayName
string

The displayName property is set if there is a display-name present in either P-Asserted-Identity: header or from: header of the incoming request triggering the /newCall request. If it is present in both headers with different values the P-Asserted-Identity display-name value is used.

fromUser
string

The value of the fromUser property is the user part of SIP URI in from: header of incoming SIP request. NOTE: It is recommended to use value of the callingParty property since this is more thrustworthy since it consider the PAI header if present. The from: header is set by the user's device and may contain any number.

xHeaders
object

This property is set to an object that contains SIP headers starting with prefix X- in the inbound SIP request that triggered the /newCall callback and their values. The object is of format {"x-header1":"value1","x-header2":"value2"}. In case of multiple header values for same header it returns an array : {"x-header3": ["val1","val2"]}.

pHeaders
object

This property is set to an object that contains SIP headers starting with prefix P- in the inbound SIP request that triggered the /newCall callback and their values. The object is of format {"p-header1":"value1","p-header2":"value2"}. In case of multiple header values for same header it returns an array : {"p-header3": ["val1","val2"]}.

copyHeaders
Array of strings

This property is set to an array that contains the names of SIP headers starting with either the prefix P- or X- to copy from the incoming call.

calledParty
string

The calledParty is the access number that is used to access the IVR.

diversionHeaders
string

This value is present if the SIP request triggering the /newCall request had any diversion headers. The value holds the content of these headers.

referredBy
string

This value is present if the SIP request triggering the /newCall request had any referred-by header. The value holds the content of this header.

paiNumber
string

The paiNumber is the E.164-number presented in the SIP PAI header

subject
string

The subject is the value in the SIP subject header

srcAddr
string

The scrAddr is the IP address of the calling SBC

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

Response Schema: application/json
action
string

Action defines what IVR should do with the participants in a connection. It can take four values:

  • call: means the calling party will get connected with the destination specified in destAddr property
  • ivr: means that participant will get connected with IVR service that will answer call an issue getIvrCommand request
  • drop: means that call will get dropped
callerPrivacy
boolean

Indicates if the calling party number should be hidden in the call that is set up from the IVR as result of the call action.

callRecording
boolean

Indicates if the call connected should be recorded. Media will be connected through the mediaservice and once the call is completed the recorded file is uploaded to the prompt storage.

contactParameters
object

This property allow custom URL parameters to be added to the contact: header of the call generated in case the action is set to call. It take an object of format {"prop1":"val1", "prop2":"val2"} as value resulting in the URL parameters prop1=val1;prop2=val2 to be appended to the contact: header.

contactUserParameters
object

This property allow custom user parameters to be added to the user part of URL in contact: header of the call generated in case the action is set to call. It take an object of format {"prop1":"val1", "prop2":"val2"} as value resulting in the URL parameters prop1=val1;prop2=val2 to be appended to the user part of the URL in contact: header.

string or Array of objects
One of
string

sip: URI to the destination to be called

displayName
string

If this property is set the value is set as display name in the the from: header of the SIP request in the case the action property is set to call

dropCode
string
Enum: "busy" "error" "numberNotFound" "numberNotActive" "dropNoMsg" "temporarilyUnavailable"

It gives extra info about why call is dropped when action is “drop”: "busy": means that customer that own access number has used all booked lines and call should be dropped with a busy signal, "numberNotFound": means that given bNumber is not defined in this ServiceNode, "numberNotActive": means that given bNumber is defined but not active in ServiceNode, "dropNoMsg": means that call should be dropped without any special message

object

Indicates if a greeting phrases should be played to participants before they are connected with each other.

playMode
string
Enum: "calleeFirst" "calleeConnected"

'calleeFirst' means the callee's prompt is played first, then caller's. 'calleeConnected' means parallel playback, i.e. caller prompt is played as soon as callee leg is connected.

object

Phrases to be played for the calling party.

phrases
Array of objects
object

Phrases to be played for the called party.

phrases
Array of objects
maxRingTime
number

Decimal number of seconds to wait for destination to answer the calls. This value is used in case no per-destination specific value is set

monitorDestAddr
string

This property is used in combination with call action in the response. When set it and the call between the two parties is connected it will automatically set up a second call to the SIP address provided in the monitorDestAddr property, the monitoring leg. This monitoring leg will provide a one way media stream containing the voice of the two connected parties. This function is typically used when developing contact center monitoring or analytics functions. Call setup progress for the call monitoring leg is reported in callNotify callback events which have the monitoringParticipant property set to true. Once the call monitoring leg have been answered a callAnswered callback event is sent having the monitoringParticipant property set to true. The connectionId and participantId property of the callAnswered callback event may be used for subsequent API calls, such as /hangupparticipant

monitorPHeaders
object

By default the P-headers are copied from the call to be monitored. This property allow custom P-headers to be added to the SIP request of the monitor call generated in case monitorDestAddr is set. It take an object of format {"x-header1":"val1", "x-header2":"val2"} as value resulting in the SIP headers and values X-Header1: val1 and X-Header2: val2. To set multiple header values for same header pass an array : {"x-header3": ["val1","val2"]}. To remove a X-header, set the value to null

monitorXHeaders
object

By default the X-headers are copied from the call to be monitored. This property allow custom X-headers to be added to the SIP request of the monitor call generated in case monitorDestAddr is set. It take an object of format {"p-header1":"val1", "p-header2":"val2"} as value resulting in the SIP headers and values P-Header1: val1 and P-Header2: val2. To set multiple header values for same header pass an array : {"p-header3": ["val1","val2"]}. To remove a P-header, set the value to null

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.

pHeaders
object

This property allow custom P- headers to be added to the SIP request of the call generated in case the action is set to call. It take an object of format {"p-header1":"val1", "p-header2":"val2"} as value resulting in the SIP headers and values P-Header1: val1 and P-Header2: val2. To set multiple header values for same header pass an array : {"p-header3": ["val1","val2"]}.

ringbackTone
string
Enum: "default" "silent" "remoteGenerated"

It defines which ringback tone should be played for calling party if action is “call”: &quot;default&quot; means that standard ringback tone should be played on inbound leg until outbound leg is answered, &quot;silent&quot; means that silence should be played on inbound leg until outbound leg is answered &quot;remoteGenerated&quot; means that the originating party localy will generate the ringback tone

recordingFileName
string

The call recording filename used when uploading the recording to the prompt storage

sessionReferenceId
object

Object that is retained for the session and passed in subsequent requests

sipDiversion
string

It defines which number should be placed in SIP-Diversion header if action is “call”. If this parameter is omitted then no SIP-Diversion header should be included in the SIP-INVITE

sipDiversionParameters
object

An object of format {param:paramValue} which sets the header parameters for the diversion header

sipFrom
string

It defines which number should be placed in SIP-From header if action is “call”. If this parameter is omitted then number in SIP-From header should be copied from the SIP-From header in the inbound leg

sipPAI
string

It defines which number should be placed in SIP-PAI header if action is “call”. If this parameter is omitted then no SIP-PAI header should be included in the SIP-INVITE

sipRPID
string

It defines which number should be placed in SIP-RemotePartyId header if action is “call”. If this parameter is omitted then no SIP-RPID header should be included in the SIP-INVITE

sipTo
string

It defines which number should be placed in SIP-To header if action is “call”. If this parameter is omitted then cNumber should be placed in To header if action is “call”

xHeaders
object

This property allow custom X- headers to be added to the SIP request of the call generated in case the action is set to call. It take an object of format {"x-header1":"val1", "x-header2":"val2"} as value resulting in the SIP headers and values X-Header1: val1 and X-Header2: val2. To set multiple header values for same header pass an array : {"x-header3": ["val1","val2"]}.

monitorSipFrom
string

It defines which number should be placed in SIP-From header and PAI header in the call monitoring call if action is “call” and “monitorDestAddr“ is set. If this parameter is omitted then number in SIP-From header of the monitoring call should be copied from the SIP-From header in the inbound leg

Request samples

Content type
application/json
{
  • "sessionId": "9bb07660-c747-11ea-afa0-bd07728b88b7",
  • "sipCallId": 5473001594892095000,
  • "ivrServer": "127.0.0.1",
  • "callingPartyPrivacy": "public",
  • "callingParty": "caller",
  • "displayName": "Carl Carlsson",
  • "fromUser": "fromUser",
  • "xHeaders": { },
  • "pHeaders": { },
  • "copyHeaders": [
    • "string"
    ],
  • "calledParty": "ivr",
  • "diversionHeaders": "&lt;sip:user@domain.com&gt;;reason=time-of-day",
  • "referredBy": "&lt;sip:referrer@referrer.example&gt;;cid=&quot;20398823.2UWQFN309shb3@referrer.example&quot;",
  • "paiNumber": "string",
  • "subject": "string",
  • "srcAddr": "string",
  • "siteId": "siteA",
  • "siteBaseUrl": "https://api.&lt;siteId&gt;.&lt;stage&gt;.iotcomms.io"
}

Response samples

Content type
application/json
{
  • "action": "drop",
  • "callerPrivacy": true,
  • "callRecording": true,
  • "contactParameters": { },
  • "contactUserParameters": { },
  • "destAddr": "string",
  • "displayName": "Donald Duck",
  • "dropCode": "busy",
  • "greeting": {
    • "playMode": "calleeFirst",
    • "caller": {
      • "phrases": [
        • { }
        ]
      },
    • "callee": {
      • "phrases": [
        • { }
        ]
      }
    },
  • "maxRingTime": 2,
  • "monitorDestAddr": "sip:monitor@domain",
  • "monitorPHeaders": { },
  • "monitorXHeaders": { },
  • "participantId": "c2af21a1-e90f-11ea-9564-1f1d01c9e7c9",
  • "pHeaders": { },
  • "ringbackTone": "default",
  • "recordingFileName": "filename.mp3",
  • "sessionReferenceId": { },
  • "sipDiversion": 123456,
  • "sipDiversionParameters": { },
  • "sipFrom": "caller",
  • "sipPAI": "caller",
  • "sipRPID": 123456,
  • "sipTo": "callee",
  • "xHeaders": { },
  • "monitorSipFrom": "monitor"
}

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

/recordingReady

POST
Request Body schema: application/json

Callback indicating that a started call recording have been complete and file is uploaded to prompt storage.

sessionId
string

The sessionId identifies the session

connectionId
string

The connectionId for the call connection that was recorded

recordingFileName
string

The file name representing the recording in the prompt storage

fileSize
integer

The size of the recorded file in bytes

ivrServer
string

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

domain
string

The domain for the tenant that use the service

event
string
Enum: "recordingSuccessful" "recordingFailed"

The type of event that triggered the /recordingReady to be sent

reason
string

Indicates cause in case of failure. Present only if event equals recordingFailed.

Responses

Request samples

Content type
application/json
{
  • "sessionId": "9bb07660-c747-11ea-afa0-bd07728b88b7",
  • "connectionId": "9bb0eee0-c747-11ea-afa0-bd07728b88b7",
  • "recordingFileName": "recording.mp3",
  • "fileSize": 4711,
  • "ivrServer": "127.0.0.1",
  • "domain": "customer.prod-eu-north-1.iotcomms.io",
  • "event": "recordingSuccessful",
  • "reason": "No callee media received"
}

/sessionCompleted

POST
Request Body schema: application/json

Event sent when a mediaservice session is ended.

sessionId
string

The sessionId identifies the current session

domain
string

The domain configured for the tenant triggering the event

sessionDuration
string

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

reason
string

participantId of calling party in the call that has been connected

sessionReferenceId
object

Object that is retained for the session and passed in subsequent requests

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.

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
{
  • "sessionId": "9bb07660-c747-11ea-afa0-bd07728b88b7",
  • "domain": "customer.prod-eu-north-1.iotcomms.io",
  • "sessionDuration": 46890510,
  • "reason": "d93f0370-c787-11eb-a47c-c9c4e460ef16",
  • "sessionReferenceId": { },
  • "ivrServer": "127.0.0.1",
  • "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"
}

Mediaservice API Service Alarms

/<domain_configured>

POST

You have not configured a domain for your service alarm notifications! You can do so here.

The configured domain for your notifications were retrieved from your settings. You can view and modify these settings here.

Request Body schema: application/json

Notifications sent by the IVR to indicate unexpected events.

type
string
Enum: "sessionError" "callEventError" "newCallEventError" "emergencyFallback" "ivrCommandError" "callError"

The type of alarm event. The following types may be sent with the specified error types

  • sessionError - Alarms raised at session level
    • maxDuration - The session was terminated since the maximum session duration was reached
  • callEventError - Alarms raised related to /callEvent callback requests
    • No response to callEvent request - The /callEvent callback did not get any response
    • Invalid sip address: <address> - The provided SIP address in destAddr property in /callEvent response is invalid
    • callEvent response with unknown action - An invalid action was provided in the /callEvent response
    • No action provided in callEvent response - Action was not provided in the /callEvent response
  • newCallEventError - Alarms raised related to /newCall callback requests
    • newCall response empty - The response the the /newCall event did not contain any body
    • newCall response without action - Action was not provided in the /newCall response
    • newCall response with unknown action - An invalid action was provided in the /newCall response
    • newCall request failed - The /newCall request failed
  • emergencyFallback - Incoming call to the mediaservice was handled according to provisioned emergency fallback logic
    • triggeredByAlways - The called destination was configured to always invoke the emergency routing logic
    • triggeredByError - The emergency routing logic was triggered due to failure to invoke the /newCall API
  • ivrCommandError - Alarms raised related to /getIvrCommand callback requests
    • phraseError - An invalid phrase was provided in the /getIvrCommand callback response
    • mediaServerError - An error occurred in the media service processing the command provided in /getIvrCommand callback response
    • Empty body in getIvrCommand response - No body was provided in the response to /getIvrCommand callback
    • getIvrCommand request error - Error sending the /getIvrCommand callback request
    • IVR command failed - Mediaservice failed to execute the command provided in the /getIvrCommand callback response
  • callError - Alarms raised in relation to the call handling to and from the media service
    • RTP media timeout - The media service was terminated due to no media (RTP packets) received from the remote party
    • invalidSdp - A call with invalid SDP was rejected by the mediaservice
    • sessionExpired - A call handled by mediaservice was terminated to to SIP session expiration, i.e. no session refresh was received for the session
    • cancelFailed - A SIP Cancel request sent by the mediaservice was responded to with a non-200 final response
    • unexpectedReinviteResponse - Am unexpected response for a SIP reinvite was receieved
domain
string

The domain that triggered the alarm event

sessionId
string

The sessionId of the call that triggered the alarm event

error
string
Enum: "maxDuration" "No response to callEvent request" "Invalid sip address: &lt;address&gt;" "callEvent response with unknown action" "No action provided in callEvent response" "newCall response empty" "newCall response without action" "newCall response with unknown action" "newCall request failed" "triggeredByAlways" "triggeredByError" "phraseError" "mediaServerError" "Empty body in getIvrCommand response" "getIvrCommand request error" "IVR command failed" "RTP media timeout" "invalidSdp" "sessionExpired" "cancelFailed" "phraseRemoteCacheTimeout"

The type of error that triggered the alarm event

errorDetails
object

Optional object that provide more details of the cause of the alarm event to be used for debug purpose.

status
string

Applicable for callError:unexpectedReinviteResponse - contains the status code received from the remote end.

participantId
string

Applicable for callError:unexpectedReinviteResponse - contains the participant ID.

user
string

Applicable for callError:unexpectedReinviteResponse - user that caused the response.

callId
string

Applicable for callError:unexpectedReinviteResponse - callId for that received the response.

Responses

Request samples

Content type
application/json
{
  • "type": "sessionError",
  • "domain": "customer.prod-eu-north-1.iotcomms.io",
  • "sessionId": "8eaf1600-c20b-11eb-9fdb-f32f171bb218",
  • "error": "maxDuration",
  • "errorDetails": { },
  • "status": "string",
  • "participantId": "string",
  • "user": "string",
  • "callId": "string"
}