Docs
Agent RPC Protocol

Agent RPC Protocol

NOTE: Feature is in Experimental stage and design may change!

Agent RPC Protocol tries to give users way to control routing of call in more programable manner with some limited set of APIs

Agent RPC is JSON protocol over Websocket and it is very close to SIP as it is all based on Request/Response transactions. This makes a bit more easier to handle sessions and reason about, instead inventing some totally different protocol.

Unlike some other systems it is designed as well that you can achieve redundancy or even load balancing. So

Use cases

API allows very simple actions and mainly intention is that you are able to influence on the routing of call. Here are some use cases that we find useful:

  • Creating complex routing that needs more authentication or identification of user
  • Simulation Agents for call testing by connecting to diagox server, like checking networking or similar.
  • Quick IVR or Auth system based on DTMF input
  • Delaying call routing while playing some Playbacks
  • Autoscaling underhood systems

Protocol

Protocol is request/response transactions as P2P communication.

All transactions/sessions are multiplexed over single WS connection, but to make this easier, SDKs will be provided

SDKs supported:

Connecting

Agent must connect (we may implement other way arround) to websocket server on port (default) 6000, and use endpoint parameter for endpoint unique name.

Example with wscat tool: wscat --connect ws://localhost:6000\?endpoint=myagent

NOTE: DO NOT EXPOSE THIS PORT as there is no yet auth system.

You can connect many agents with same endpoint ID, where in this case traffic will be randomly load balanced.

Example

Here simple use case of answering a call and running playback and redirecting

agentrpc

Diagox has endpoint myagent and voicebot configuration for routing:

endpoints:
  incoming:
    match: 
      type: "ip"
      values: ["10.10.0.1/24"]

  voicebot: # Address of record
    uri: "sip:voicebot:5080" 

  myagent: 
    match:
      type: "agent"

Requests/Responses

Request fields:

  • id - unique id of request
  • did - dialog id
  • op - operation or name of request
  • data - payload object

Response fields:

  • id - unique id of request
  • did - dialog id
  • code - 100-600 status codes
  • reason - Status code reason
  • data - payload object

Response can be

  • 100 - 200 as Provisional. This are mostly informational for request that need to take time to complete like playing a file
  • 200 - 600 as Final

Example

// Request
{
  "id": "8a4d9f5e-2b63-4854-82be-9f24b25d9d93",
  "did": "dea5aa08-f964-434b-92b5-7fc75cf4662b__734dee05-fcd9-4067-85ac-7ccaf81c1544__JraXcfuPG77WpJt2",
  "op": "invite",
  "data": null
}

// Response
{
  "id": "8a4d9f5e-2b63-4854-82be-9f24b25d9d93",
  "did": "dea5aa08-f964-434b-92b5-7fc75cf4662b__734dee05-fcd9-4067-85ac-7ccaf81c1544__JraXcfuPG77WpJt2",
  "code": 200,
  "reason": "OK"
  "data": null
}

Diagox requests

For incoming call Diagox will send invite request for agent to accept or not. In case of not accepting depending on response diagox can send this invite to other agent if loadbalancing is in place.

When call is hanguping or being redirected bye will be sent as final request. Generally Agent should just respond 200 but it will hold up call untill this happens.

invite

New call session initiated. Must be accepted by agent with 200 OK or rejected or redirected.
Payload:

  • callID - SIP callID of dialog. Useful for tracing
  • from - From number or SIP From header user part
  • to - To number or SIP To header user part

bye

Indication that call is exiting either due to remote hangup, agent hangup or redirect.

Agent requests

ring

Starts ring with SIP 180.

answer

Answers call and voice media is established.

play

Playing file or url.
Payload:

  • uri - Uri format for playing wav files
    • file: file://somefile.wav - Files by default are looked relative to diagox executable or configured Playback Dir
    • http: https://mycoolfiles/sound.wav

read_dtmf

Reading DTMF. Payload:

  • duration_sec - how long to wait for dtmf(s) in seconds
  • termination - stop on this termination digit

hangup

Hangups a call.

redirect

Redirects call to endpoint, after which call control is terminated. Payload

WebRTC