Skip to content

Latest commit

 

History

History
807 lines (658 loc) · 18.3 KB

Commands.md

File metadata and controls

807 lines (658 loc) · 18.3 KB
Raw

JSON-RPC Protocol Documentation

Once a WebSocket channel is established between the client and the API, communication will take place strictly using JSON messages which follow the JSON-RPC 2.0 request/response/notification protocol. Note that API clients are expected to process notifications from the API, while their launched commands are being handled asynchronously.

The Call API daemon receives a set of commands as JSON-RPC requests. A typical command would look as it follows (note that <...> indicates a placeholder for the actual values):

{
	"jsonrpc": "2.0"
	"id": <request-id>,
	"method": "<command>",
	"params": <params>
}

The request will contain the following placeholders:

  • request-id: an unique identifier of the JSON-RPC request
  • method: of the commands provided by the Call API engine
  • params: a JSON object containing different parameters, mandatory or optional, required by the command to run

For each command sent, the JSON-RPC client will immediately receive a response from the server, with the following format:

{
	"jsonrpc": "2.0"
	"id": <request-id>,
	"result": {
		"cmd_id": "<cmd-id>",
		"event": "Started",
	}
}

The JSON above contains the following placeholders:

  • cmd-id: an identifier of the command sent. If a cmd_id node has been specified in the request, then the same id will be returned otherwise an unique uuid will be generated for the command; this id would be present in all the following notifications sent for this specific command.
  • request-id: is the identifier sent in the JSON-RPC request

In case of a failure to initiate the command, a standard JSON-RPC error will be triggered, with the following format:

{
	"jsonrpc": "2.0"
	"id": <request-id>,
	"error": {
		"code": <code>,
		"message": "<reason>"
	}
}

The placeholders for an error will contain the following values:

  • request-id: the same identifier received in the JSON-RPC request
  • code: an integer indicated the code of the error
  • reason: a string containing the reason of the error

If, however, the command invocation was successful, the Call API engine will start to generate JSON-RPC notifications about the progress of the command. These notifications look like this:

	"jsonrpc": "2.0"
	"method": "<command>",
	"params": {
		"cmd_id": "<cmd-id>",
		"event": "<event>",
		"data": "<data>",
	}

A notification will contain the following values as placeholders:

  • command: the command that triggered this notification
  • cmd-id: the id of the command, as provided in the initial JSON-RPC response
  • event: one of the following values:
    • Error: indicates an error has been triggered
    • Ended: indicates that the command has been completed
    • an arbitrary name describing the status of the execution
  • data: optional JSON node, containing extra information about the error, or the progress of the command being executed; note that the Ended event does not have a data node.

Commands

CallStart

Parameters

  • "caller" (string, mandatory)
  • "callee" (string, mandatory)

Events

  • CallerAnswered: triggered when the caller answered the initial call
    • caller: the caller that has just answered the call
    • callee: the callee that is being reached next
  • Transferring: triggered when the caller is trying to reach the callee
    • caller: the caller of the new call
    • destination: the SIP URI that is being called
  • TransferStart: triggered when the caller starts the call to callee
    • callid: the Call-ID of the new call
    • caller: the caller of the new call
    • callee: the callee that is being called
  • TransferPending: optional, contains extra information provided by the UAC regarding the new call
    • callid: the Call-ID of the new call
    • caller: the caller of the new call
    • callee: the callee of the new call
    • extra: optional, extra information provided by the caller
  • CalleeAnswered: triggered when the callee answers the call
    • callid: the Call-ID of the new call
    • caller: the caller of the new call
    • callee: the callee of the new call

Example JSON-RPC flow:

1) WS client ----------> API

{
    "method": "CallStart",
    "params": {
        "caller": "sip:[email protected]",
        "callee": "sip:[email protected]"
    },
    "id": "831717ed97e5",
    "jsonrpc": "2.0"
}

2) WS client <---------- API

{
    "result": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "status": "Started"
    },
    "id": "831717ed97e5",
    "jsonrpc": "2.0"
}

3) WS client <---------- API

{
    "method": "CallStart",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "status": "CallerAnswered"
        "data": {
            "caller": "sip:[email protected]",
            "callee": "sip:[email protected]"
        }
    },
    "jsonrpc": "2.0"
}

4) WS client <---------- API

{
    "method": "CallStart",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "status": "Transferring"
        "data": {
            "caller": "sip:[email protected]",
            "callee": "sip:[email protected]"
        }
    },
    "jsonrpc": "2.0"
}

5) WS client <---------- API

{
    "method": "CallStart",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "status": "TransferStart"
        "data": {
            "callid": "1fc8043a-3f89-49f9-8f8c-4c284faf69e3",
            "caller": "sip:[email protected]",
            "callee": "sip:[email protected]"
        }
    },
    "jsonrpc": "2.0"
}

6) WS client <---------- API

{
    "method": "CallStart",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "status": "TransferPending"
        "data": {
            "callid": "1fc8043a-3f89-49f9-8f8c-4c284faf69e3",
            "caller": "sip:[email protected]",
            "callee": "sip:[email protected]",
            "extra":"100 Trying"
        }
    },
    "jsonrpc": "2.0"
}

7) WS client <---------- API

{
    "method": "CallStart",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "status": "CalleeAnswered"
        "data": {
            "callid": "1fc8043a-3f89-49f9-8f8c-4c284faf69e3",
            "caller": "sip:[email protected]",
            "callee": "sip:[email protected]"
        }
    },
    "jsonrpc": "2.0"
}

8) WS client <---------- API

{
    "method": "CallStart",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178"
        "status": "Ended"
    },
    "jsonrpc": "2.0"
}

CallBlindTransfer

Parameters

  • "callid" (string, mandatory) - the SIP Call-ID of the targeted dialog
  • "leg" (string, mandatory) - which party to transfer. Possible values: "caller", "callee"
  • "destination" (string, mandatory) - SIP URI of the blind transfer target

Events

  • Transferring: triggered when the transferrer has accepted the transfer
    • destination: the destination URI specified in the request
  • TransferStart: triggered when the leg starts the call the new destination
    • callid: the Call-ID of the new call
    • destination: SIP URI of the party that we are transferring to - note that the URI might be altered after the lookup has been performed
  • TransferPending: optional, triggered when the participant starts the transferring call
    • callid: the Call-ID of the new call
    • destination: SIP URI of the party that we are transferring to
    • extra: optional, extra information provided by the transferrer
  • TransferSuccessful: triggered when the destination accepted the new call
    • callid: the Call-ID of the new call
    • destination: SIP URI of the party that we are transferring to

Example JSON-RPC flow:

# 1) WS client ----------> API

{
    "method": "CallBlindTransfer",
    "params": {
        "callid": "[email protected]",
        "leg": "callee",
        "destination": "sip:[email protected]"
    },
    "id": "831717ed97e5",
    "jsonrpc": "2.0"
}

# 2) WS client <---------- API

{
    "result": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "status": "Started"
    },
    "id": "831717ed97e5",
    "jsonrpc": "2.0"
}

# 3) WS client <---------- API

{
    "method": "CallBlindTransfer",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "Transferring",
        "data": {
            "destination": "sip:[email protected]"
        }
    },
    "jsonrpc": "2.0"
}

# 4) WS client <---------- API

{
    "method": "CallBlindTransfer",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "TransferStart"
        "data": {
            "callid": "29ad6fdb-7806-4c17-b235-02b8f9fad1ae",
            "destination": "sip:[email protected]"
        }
    },
    "jsonrpc": "2.0"
}

# 5) WS client <---------- API

{
    "method": "CallBlindTransfer",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "TransferSuccessful"
        "data": {
            "callid": "29ad6fdb-7806-4c17-b235-02b8f9fad1ae",
            "destination": "sip:[email protected]"
        }
    },
    "jsonrpc": "2.0"
}

# 6) WS client <---------- API

{
    "method": "CallBlindTransfer",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178"
        "event": "Ended"
    },
    "jsonrpc": "2.0"
}

CallAttendedTransfer

Parameters

  • "callidA" (string, mandatory) - the SIP Call-ID of the dialog #1
  • "legA" (string, mandatory) - which party to transfer from dialog #1. Possible values: "caller", "callee"
  • "callidB" (string, mandatory) - the SIP Call-ID of the dialog #2
  • "legB" (string, mandatory) - which party to transfer from dialog #2. Possible values: "caller", "callee"

Events

  • Transferring: triggered when the transferrer has accepted the transfer
  • TransferStart: triggered when the transferring leg of Call-ID of the dialog #1 is calling the leg in dialog #2
    • callid: the Call-ID of the new call
    • destination: SIP URI of the party that we are transferring to
  • TransferPending: optional, triggered when the participant starts the transferring call
    • callid: the Call-ID of the new call
    • destination: SIP URI of the party that we are transferring to
    • extra: optional, extra information provided by the transferrer
  • TransferSuccessful: triggered when the destination accepted the new call
    • callid: the Call-ID of the new call
    • destination: SIP URI of the party that we are transferring to

Example JSON-RPC flow:

# 1) WS client ----------> API

{
    "method": "CallAttendedTransfer",
    "params": {
        "callidA": "[email protected]",
        "legA": "caller",
        "callidB": "0ba2cf53-9a78-41de-8fe6-f2e5bb4d1a1e",
        "legB": "callee",
    }

    "id": "831717ed97e5",
    "jsonrpc": "2.0"
}

# 2) WS client <---------- API

{
    "result": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "status": "Started"
    }

    "id": "831717ed97e5",
    "jsonrpc": "2.0"
}

# 3) WS client <---------- API

{
    "method": "CallAttendedTransfer",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "Transferring"
    },
    "jsonrpc": "2.0"
}

# 4) WS client <---------- API

{
    "method": "CallAttendedTransfer",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "TransferStart"
        "data": {
            "callid": "29ad6fdb-7806-4c17-b235-02b8f9fad1ae",
            "destination": "sip:[email protected]"
        }
    },
    "jsonrpc": "2.0"
}

# 5) WS client <---------- API

{
    "method": "CallAttendedTransfer",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "TransferSuccessful"
        "data": {
            "callid": "29ad6fdb-7806-4c17-b235-02b8f9fad1ae",
            "destination": "sip:[email protected]"
        }
    },
    "jsonrpc": "2.0"
}

# 6) WS client <---------- API

{
    "method": "CallAttendedTransfer",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178"
        "event": "Ended"
    },
    "jsonrpc": "2.0"
}

CallHold

Parameters

  • "callid" (string, mandatory) - the SIP Call-ID of the target dialog

Events

  • CallHolding: triggered when the command was received by the proxy
  • CallHoldStart: triggered when the proxy sends a hold INVITE to one of the legs
    • leg: the call's leg that the message is being sent to (caller or callee)
  • CallHoldSuccessful: triggered when one of the legs successfully accepted the call hold
    • leg: the call's leg that completed the call hold (caller or callee)

Example JSON-RPC flow:

# 1) WS client ----------> API

{
    "method": "CallHold",
    "params": {
        "callid": "[email protected]",
    },
    "id": "831717ed97e5",
    "jsonrpc": "2.0"
}

# 2) WS client <---------- API

{
    "result": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "status": "Started"
    },
    "id": "831717ed97e5",
    "jsonrpc": "2.0"
}

# 3) WS client <---------- API

{
    "method": "CallHold",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "CallHolding"
    },
    "jsonrpc": "2.0"
}

# 4) WS client <---------- API

{
    "method": "CallHold",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "CallHoldStart",
        "data": {
            "leg": "caller"
        },
    },
    "jsonrpc": "2.0"
}

# 5) WS client <---------- API

{
    "method": "CallHold",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "CallHoldStart"
        "data": {
            "leg": "callee"
        },
    },
    "jsonrpc": "2.0"
}

# 6) WS client <---------- API

{
    "method": "CallHold",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "CallHoldSuccessful"
        "data": {
            "leg": "caller"
        },
    },
    "jsonrpc": "2.0"
}

# 7) WS client <---------- API

{
    "method": "CallHold",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "CallHoldSuccessful"
        "data": {
            "leg": "callee"
        },
    },
    "jsonrpc": "2.0"
}

# 8) WS client <---------- API

{
    "method": "CallHold",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "Ended"
    },
    "jsonrpc": "2.0"
}

CallUnhold

Parameters

  • "callid" (string, mandatory) - the SIP Call-ID of the target dialog

Events

  • CallUnholding: triggered when the command was received by the proxy
  • CallUnholdStart: triggered when the proxy sends a hold INVITE to one of the legs
    • leg: the call's leg that the message is being sent to (caller or callee)
  • CallUnholdSuccessful: triggered when one of the legs successfully resumes
    • leg: the call's leg that resumed the call (caller or callee)

Example JSON-RPC flow:

# 1) WS client ----------> API

{
    "method": "CallUnhold",
    "params": {
        "callid": "[email protected]",
    },
    "id": "831717ed97e5",
    "jsonrpc": "2.0"
}

# 2) WS client <---------- API

{
    "result": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "status": "Started"
    },
    "id": "831717ed97e5",
    "jsonrpc": "2.0"
}

# 3) WS client <---------- API

{
    "method": "CallUnhold",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "CallUnholding"
    },
    "jsonrpc": "2.0"
}

# 4) WS client <---------- API

{
    "method": "CallUnhold",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "CallUnholdStart",
        "data": {
            "leg": "caller"
        },
    },
    "jsonrpc": "2.0"
}

# 5) WS client <---------- API

{
    "method": "CallUnhold",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "CallUnholdStart"
        "data": {
            "leg": "callee"
        },
    },
    "jsonrpc": "2.0"
}

# 6) WS client <---------- API

{
    "method": "CallUnhold",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "CallUnholdSuccessful"
        "data": {
            "leg": "caller"
        },
    },
    "jsonrpc": "2.0"
}

# 7) WS client <---------- API

{
    "method": "CallUnhold",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "CallUnholdSuccessful"
        "data": {
            "leg": "callee"
        },
    },
    "jsonrpc": "2.0"
}

# 8) WS client <---------- API

{
    "method": "CallUnhold",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "Ended"
    },
    "jsonrpc": "2.0"
}

CallEnd

Parameters

  • "callid" (string, mandatory) - the SIP Call-ID of the target dialog

Events

NO events

Example JSON-RPC flow:

# 1) WS client ----------> API

{
    "method": "CallEnd",
    "params": {
        "callid": "[email protected]"
    },
    "id": "831717ed97e5",
    "jsonrpc": "2.0"
}

# 2) WS client <---------- API

{
    "result": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "status": "Started"
    },
    "id": "831717ed97e5",
    "jsonrpc": "2.0"
}

# 3) WS client <---------- API

{
    "method": "CallEnd",
    "params": {
        "cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
        "event": "Ended"
    }
    "jsonrpc": "2.0"
}

Echo

Command that receives arbitrary parameters and outputs them back as a notification. This command is useful to test connectivity to the API server.

Parameters

Any parameter

Events

  • Reply: contains a JSON object with the same JSON as specified in the request.

Example JSON-RPC flow:

1) WS client ----------> API

{
    "method": "Echo",
    "params": {
        "test": "echo",
    },
    "id": "33f6c98c821b",
    "jsonrpc": "2.0"
}

2) WS client <---------- API

{
    "result": {
        "cmd_id": "0f8a1664-01e2-46fe-ae55-e02715afee02",
        "event": "Started"
    },
    "id": "33f6c98c821b",
    "jsonrpc": "2.0"
}

3) WS client <---------- API

{
    "method": "Echo",
    "params": {
        "cmd_id": "0f8a1664-01e2-46fe-ae55-e02715afee02",
        "event": "Reply",
        "data": {"test":"echo"}
    },
    "jsonrpc": "2.0"
}

4) WS client <---------- API

{
    "method": "Echo",
    "params": {
        "cmd_id": "0f8a1664-01e2-46fe-ae55-e02715afee02",
        "event": "Ended"
    },
    "jsonrpc": "2.0"
}