The Call API is a front-end layer for SIP Proxies (such as OpenSIPS) managing more advanced SIP call flows. Combining built-in SIP scenarios (such as the ones from RFC 5359) with real-time notifications as the call commands take place, the API is meant to help VoIP system developers build complex SIP services with ease, altogether while providing live reporting for such services.
The API listens for WebSocket connections on ws://localhost:5059/call-api and talks JSON-RPC 2.0 over them.
go get github.com/OpenSIPS/call-api
TODO
Below are the API's commands available for building your JSON-RPC requests. Read the documentation of each command for a listing of its input parameters and their accepted values:
- CallStart - start a call between two participants
- CallBlindTransfer - perform an unattended call transfer (see RFC 5359 example)
- CallAttendedTransfer - perform an attended call transfer (see RFC 5359 example)
- CallHold - put one or both participants on hold
- CallUnHold - resume an on-hold call
- CallEnd - terminate an ongoing call
By default, the API listens on ws://localhost:5059/call-api. Below is an example way of launching a CallStart command using an API client written in Go:
go run cmd/call-api-client/main.go \
-method CallStart \
-params '{"caller": "sip:alice@localhost", "callee": "sip:bob@localhost"}'
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.
- "caller" (string, mandatory)
- "callee" (string, mandatory)
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": "Event",
"params": {
"cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
"data": "CALL_ANSWER"
}
"jsonrpc": "2.0"
}
4) WS client <---------- API
{
"method": "Event",
"params": {
"cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
"data": "TRANSFER_ACCEPT"
}
"jsonrpc": "2.0"
}
5) WS client <---------- API
{
"method": "Event",
"params": {
"cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
"data": "CALL_START"
}
"jsonrpc": "2.0"
}
6) WS client <---------- API
{
"method": "Event",
"params": {
"cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
"data": "CALL_ANSWER"
}
"jsonrpc": "2.0"
}
7) WS client <---------- API
{
"method": "Ended",
"params": {
"cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178"
}
"jsonrpc": "2.0"
}
- "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
# 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": "Event",
"params": {
"cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
"data": "TRANSFER_ACCEPT"
}
"jsonrpc": "2.0"
}
# 4) WS client <---------- API
{
"method": "Event",
"params": {
"cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
"data": "CALL_START"
}
"jsonrpc": "2.0"
}
# 5) WS client <---------- API
{
"method": "Ended",
"params": {
"cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178"
}
"jsonrpc": "2.0"
}
- "callid_a" (string, mandatory) - the SIP Call-ID of the dialog #1
- "leg_a" (string, mandatory) - which party to transfer from dialog #1. Possible values: "caller", "callee"
- "callid_b" (string, mandatory) - the SIP Call-ID of the dialog #2
- "leg_b" (string, mandatory) - which party to transfer from dialog #2. Possible values: "caller", "callee"
- "destination" (string, mandatory) - SIP URI of the attended transfer's destination
# 1) WS client ----------> API
{
"method": "CallAttendedTransfer",
"params": {
"callid_a": "[email protected]",
"leg_a": "caller",
"callid_b": "0ba2cf53-9a78-41de-8fe6-f2e5bb4d1a1e",
"leg_b": "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": "Event",
"params": {
"cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
"data": "TRANSFER_ACCEPT"
}
"jsonrpc": "2.0"
}
# 4) WS client <---------- API
{
"method": "Event",
"params": {
"cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
"data": "CALL_START"
}
"jsonrpc": "2.0"
}
# 5) WS client <---------- API
{
"method": "Ended",
"params": {
"cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178"
}
"jsonrpc": "2.0"
}
- "callid" (string, mandatory) - the SIP Call-ID of the target dialog
- "leg" (string, optional) - party to put on hold ("caller" or "callee"). If missing, both call participants will be put on hold
# 1) WS client ----------> API
{
"method": "CallHold",
"params": {
"callid": "[email protected]",
"leg": "caller"
}
"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": "Event",
"params": {
"cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
"data": "CALL_HOLD"
}
"jsonrpc": "2.0"
}
# 4) WS client <---------- API
{
"method": "Ended",
"params": {
"cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178"
}
"jsonrpc": "2.0"
}
- "callid" (string, mandatory) - the SIP Call-ID of the target dialog
# 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": "Event",
"params": {
"cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178",
"data": "CALL_UNHOLD"
}
"jsonrpc": "2.0"
}
# 4) WS client <---------- API
{
"method": "Ended",
"params": {
"cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178"
}
"jsonrpc": "2.0"
}
- "callid" (string, mandatory) - the SIP Call-ID of the target dialog
# 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": "Ended",
"params": {
"cmd_id": "b8179f1e-b4e4-4ac7-9990-4bf64f084178"
}
"jsonrpc": "2.0"
}