Sending metadata

In various call-center scenarios, it's desirable to pass information from the bot to the call-center system. This can be used for several purposes, for example:

• When escalating to a human agent (see Transferring the call), the current state of the conversation can be passed to the call-center, to facilitate better selection of the agent.

• Before disconnecting the call, the bot can update the outcome of the conversation so it can be documented in the call-center database.

• When performing Agent assist, the bot can pass real-time suggestions to the agent.

The information (metadata) is given as a JSON object and can be forwarded to the call center in one of the following ways:

• HTTP POST request to a provided URL

• The URL can be populate according to conversation's attributes. See Dynamically setting parameters for more details.

• SIP INFO messages

• Over the metadata event, while using the agent assist API.

Alternatively the information (metadata) can be fetched after the call has ended by rest API (see Passing SIP headers to the bot).

How do I use it?

Configuration

For sending the metadata using SIP INFO messages to the peer of the conversation, the administrator should set the sendMetadataAsSipInfo to true.

For sending HTTP POST requests, the administrator should set the sendMetaDataUrl parameter

"sendMetaDataUrl": "https://my-host/call/${botMessageMetadata.caller}"

For using HTTP Basic authentication for HTTP requests, the following parameters should be configured inside the credentials parameter of the bot:

Event

For sending metadata, the bot should send the sendMetaData event.

See Sending activities page for instructions on how to send events using your bot framework.

The metadata should be specified in the "value" attribute, which can contain any valid JSON object.

For example:

{
  "type": "event",
  "name": "sendMetaData",
  "value": {
    "myParamName": "myParamValue"
  }
}

{
  "type": "event",
  "name": "sendMetaData",
  "value": {
    "myParamName": "myParamValue"
  }
}

{
  "value": {
    "myParamName": "myParamValue"
  }
}

[Activity
  "type": "event",
  "name": "sendMetaData",
  "value": ${json(`
    "myParamName": "myParamValue"
   `)}
]

{
  "activities": [{
    "type": "event",
    "name": "sendMetaData",
    "value": {
      "myParamName": "myParamValue"
    }
  }]
}

{
  "activities": [{
    "type": "event",
    "name": "sendMetaData",
    "value": {
      "myParamName": "myParamValue"
    }
  }]
}

How the metadata is sent?

When handling the sendMetaData event, VoiceAI Connect performs one of the following (according to configuration):

• HTTP POST request

  The metadata is sent as the HTTP request body.

  For example:

  POST /my-path/12345 HTTP/1.1
  Host: server.example.com
  Content-Type: application/json;charset=UTF-8
  
  {
    "myParamName": "myParamValue"
  }

• SIP INFO message

  The metadata is sent inside the "data" element in the body.

  For example:

  INFO sip:alice@pc33.example.com SIP/2.0
  Via: SIP/2.0/UDP 192.0.2.2:5060;branch=z9hG4bKnabcdef
  To: Bob <sip:bob@example.com>;tag=a6c85cf
  From: Alice <sip:alice@example.com>;tag=1928301774
  Call-Id: 123456789@example.com
  CSeq: 314333 INFO
  Content-Type: application/json
  Content-Length: 59
  
  {
    "data": {
      "myParamName": "myParamValue"
    }
  }
  

• Metadata event

  When the client is using Agent assist API.