Работа c API¶

На данной станице будет показано как начать работу с API на примере задачи:

создания SIP учеток для телефонов;
создания комнаты конфренции;
вызова телефонов и присоединения его к конференции.

Термины и определения¶

api_url - базовый URI используемый для выполнения запросов к виртуальной АТС. Далее в примерах используется значение https://api.rcsnet.ru/v2;
account_id - идентификатор виртуальной АТС, используется для указания набора сервисов предоставляемых тому или другому клиенту;
api_key - токен используемый для генерации сессионного пароля. Значение api_key необходимо получить у вашего менеджера;
auth_token - сессионный ключ, используется для аутентификации при выполнении операций с виртуальной АТС;

Генерация сессионного пароля¶

Перед началом каких-либо операций с виртуальной АТС требуется сгенерировать сессионый пароль auth_token. Пароль гененирируется запросом следующего вида

curl -X PUT {api_uri}/api_auth \
     -H 'Content-Type: application/json' \
     -d '{ "data" : { "api_key" : "{api_key}" }}'

Например:

curl -X PUT https://api.rcsnet.ru/v2/api_auth \
     -H 'Content-Type: application/json' \
     -d '{ "data" : { "api_key" : "my_complex_api_key_goes_here" }}'

В результате будет получен JSON ответ следующего вида:

{
   "page_size":1,
   "data":{
      "account_id":"abcdef1234567890abcdef1234567890",
      "reseller_id":"abcdef1234567890abcdef1234567890",
      "is_reseller":false,
      "account_name":"My Account Name",
      "language":"ru-RU"
   },
   "revision":"automatic",
   "request_id":"5a5e8c680f64ddbf8c56e8727660320b",
   "status":"success",
   "auth_token":"xxxxxxxxxxxxxxxxxxxxxxxxx"
}

В полученном ответе нас интересует значения account_id и auth_token, которые необходимо будет использовать в дальнейших запросах.

Отображение списка SIP устройств¶

Для отображения списка SIP устройств необходимо выполнить запрос вида:

curl -X GET {api_uri}/accounts/{account_id}/devices \
     -H 'X-Auth-Token: {auth_token}' \
     -H 'Accept: application/json'

Например:

curl -X GET https://api.rcsnet.ru/v2/accounts/abcdef1234567890abcdef1234567890/devices \
     -H 'X-Auth-Token: xxxxxxxxxxxxxxxxxxxxxxxxx' \
     -H 'Accept: application/json'

В результате будет получен ответ следующего вида

{
   "page_size":2,
   "data":[
      {
         "id":"14b32dddd09b255c5777555f5583217c",
         "name":"1001",
         "mac_address":"",
         "enabled":true,
         "device_type":"sip_device"
      },
      {
         "id":"0854505837c4bfd5dcf54b044a538535",
         "name":"1002",
         "mac_address":"",
         "enabled":true,
         "device_type":"sip_device"
      }
   ],
   "revision":"590923c4063889b493e58d16aaba776f",
   "request_id":"ccc28351d7f7ac08dff3ea2f9325bbdf",
   "status":"success",
   "auth_token":"c032acdb99279024f1834b1e91f408cf"
}

В ответе нас интересует объект ‘data’. Данный объект содержит краткое описание параметров SIP телефонов. Обратите внимание на параметр ‘id’ телефона, он будет использоваться для иницирования вызова на телефон.

Создание объекта конференции¶

В данном примере будет показано как создать конференцию. Следует отметить что после создания конференции ее еще нельзя вызвать с телефона. Требуется создать объект ‘callflow’ с описанием схемы обработки звонка в котором можно просто вызвать объект конференции или сперва проиграть какое-то объявление и потому вызвать объект конференции. Итак для создания конференции необходимо выполнить запрос вида:

curl -X PUT {api_uri}/accounts/{account_id}/conferences \
     -H 'Content-Type: application/json' \
     -H 'X-Auth-Token: {auth_token}' \
     -d '{"data":{"name":"{conference_name}"}}'

Например:

curl -X PUT https://api.rcsnet.ru/v2/accounts/abcdef1234567890abcdef1234567890/conferences \
     -H 'Content-Type: application/json' \
     -H 'X-Auth-Token: xxxxxxxxxxxxxxxxxxxxxxxxx' \
     -d '{"data":{"name":"my_first_conference","member":{"join_muted":false}}}'

В результате будет получен ответ следующего вида

{
   "data":{
      "name":"my_first_conference",
      "conference_numbers":[],
      "member":{
         "join_deaf":false,
         "join_muted":false,
         "numbers":[],
         "pins":[]
      },
      "moderator":{
         "join_deaf":false,
         "join_muted":false,
         "numbers":[],
         "pins":[]
      },
      "play_name":false,
      "id":"836d23419b739dee2503d89c8bf26b3a"
   },
   "revision":"1-e7a3f391f0367c417611157837134d4e",
   "request_id":"6c43a5bd757aea7369cb0bb0b3737d33",
   "status":"success",
   "auth_token":"02d6916158bf3a94d95c669d581cf7e0"
}

В ответе нас интересует объект ‘data’. Данный объект содержит краткое описание параметров созданной конференции. Обратите внимание на параметр ‘id’ конференции, он будет использоваться при создании ‘callflow’- схемы обработки вызова.

Вывод списка конференций¶

Для вывода перечня соданных конференций необходимо выполнить запрос вида:

curl -X GET {api_uri}/accounts/{account_id}/conferences \
     -H 'X-Auth-Token: {auth_token}'

Например:

curl -X GET https://api.rcsnet.ru/v2/accounts/abcdef1234567890abcdef1234567890/conferences \
     -H 'X-Auth-Token: xxxxxxxxxxxxxxxxxxxxxxxxx'

В результате будет получен ответ следующего вида

{
   "page_size":2,
   "data":[
      {
         "id":"d2bc7ac32168ac4d054dd68ae67c3a01",
         "name":"my_first_conference",
         "member":{
            "join_muted":false,
            "join_deaf":false,
            "numbers":[],
            "pins":[]
         },
         "moderator":{
            "join_deaf":false,
            "join_muted":false,
            "numbers":[],
            "pins":[]
         },
         "is_locked":false,
         "duration":0,
         "moderators":0,
         "members":0
      },
      {
         "id":"836d23419b739dee2503d89c8bf26b3a",
         "name":"my_second_conference",
         "member":{
            "join_deaf":false,
            "join_muted":false,
            "numbers":[],
            "pins":[]
         },
         "moderator":{
            "join_deaf":false,
            "join_muted":false,
            "numbers":[],
            "pins":[]
         },
         "is_locked":false,
         "duration":0,
         "moderators":0,
         "members":0
      }
   ],
   "revision":"eaf416ff10e53f1841abb109dca4c998",
   "request_id":"0d63e455642feb8d18e49ddf11335a77",
   "status":"success",
   "auth_token":"02d6916158bf3a94d95c669d581cf7e0"
}

Вывод конфигурации конференции¶

Для вывода полной информации о конфигурации конференций необходимо выполнить запрос вида:

curl -X GET {api_uri}/accounts/{account_id}/conferences/{conference_id} \
     -H 'X-Auth-Token: {auth_token}'

Например:

curl -X GET https://api.rcsnet.ru/v2/accounts/abcdef1234567890abcdef1234567890/conferences/d2bc7ac32168ac4d054dd68ae67c3a01 \
     -H 'X-Auth-Token: xxxxxxxxxxxxxxxxxxxxxxxxx'

В результате будет получен ответ следующего вида

{
   "data":{
      "member":{
         "join_muted":false,
         "join_deaf":false,
         "numbers":[],
         "pins":[]
      },
      "name":"my_first_conference",
      "conference_numbers":[],
      "moderator":{
         "join_deaf":false,
         "join_muted":false,
         "numbers":[],
         "pins":[]
      },
      "play_name":false,
      "id":"d2bc7ac32168ac4d054dd68ae67c3a01",
      "_read_only":{
         "members":0,
         "moderators":0,
         "duration":0,
         "is_locked":false,
         "participants":[]
      }
   },
   "revision":"1-ed3b508ec557c82dd3374a0ad1e5bddb",
   "request_id":"fb1b13e42bda123a4cb3a08043f74113",
   "status":"success",
   "auth_token":"02d6916158bf3a94d95c669d581cf7e0"
}

Удаление объекта конференции¶

Для удаление конференции необходимо выполнить запрос вида:

curl -X DELETE {api_uri}/accounts/{account_id}/conferences/{conference_id} \
     -H 'X-Auth-Token: {auth_token}'

Например:

curl -X DELETE https://api.rcsnet.ru/v2/accounts/abcdef1234567890abcdef1234567890/conferences/d2bc7ac32168ac4d054dd68ae67c3a01 \
     -H 'X-Auth-Token: xxxxxxxxxxxxxxxxxxxxxxxxx'

В результате будет получен ответ следующего вида

{
   "data":{
      "member":{
         "join_muted":false,
         "join_deaf":false,
         "numbers":[],
         "pins":[]
      },
      "name":"my_first_conference",
      "conference_numbers":[],
      "moderator":{
         "join_deaf":false,
         "join_muted":false,
         "numbers":[],
         "pins":[]
      },
      "play_name":false,
      "id":"d2bc7ac32168ac4d054dd68ae67c3a01",
      "_read_only":{
         "members":0,
         "moderators":0,
         "duration":0,
         "is_locked":false,
         "participants":[]
      }
   },
   "revision":"1-ed3b508ec557c82dd3374a0ad1e5bddb",
   "request_id":"fb1b13e42bda123a4cb3a08043f74113",
   "status":"success",
   "auth_token":"02d6916158bf3a94d95c669d581cf7e0"
}

Обновление конфигурации конференции¶

Для изменения конфигурации конференции необходимо выполнить запрос вида:

curl -X POST {api_uri}/accounts/{account_id}/conferences/{conference_id} \
     -H 'X-Auth-Token: {auth_token}' \
     -H 'Content-Type: application/json' \
     -d @- << EOF
  {
     "data":{
        "member":{
           "join_deaf":false,
           "join_muted":false,
           "numbers":[]
        },
        "name":"aabbccda",
        "moderator":{
           "join_deaf":false,
           "join_muted":false,
           "numbers":[],
           "pins":[]
        },
        "play_name":false,
        "id":"836d23419b739dee2503d89c8bf26b3a",
        "ui_metadata":{
           "ui":"kazoo-ui"
        }
     },
     "verb":"POST"
  }
  EOF

Например:

curl -X POST https://api.rcsnet.ru/v2/accounts/abcdef1234567890abcdef1234567890/conferences/d2bc7ac32168ac4d054dd68ae67c3a01 \
     -H 'X-Auth-Token: xxxxxxxxxxxxxxxxxxxxxxxxx' \
     -H 'Content-Type: application/json' \
     -d @- << EOF
  {
     "data":{
        "member":{
           "join_deaf":false,
           "join_muted":false,
           "numbers":[]
        },
        "name":"aabbccda",
        "moderator":{
           "join_deaf":false,
           "join_muted":false,
           "numbers":[],
           "pins":[]
        },
        "play_name":false,
        "id":"836d23419b739dee2503d89c8bf26b3a",
        "ui_metadata":{
           "ui":"kazoo-ui"
        }
     },
     "verb":"POST"
  }
  EOF

В результате будет получен ответ следующего вида

{
   "data":{
      "member":{
         "join_deaf":false,
         "join_muted":false,
         "numbers":[],
         "pins":[]
      },
      "name":"aabbccda",
      "moderator":{
         "join_deaf":false,
         "join_muted":false,
         "numbers":[],
         "pins":[]
      },
      "play_name":false,
      "id":"836d23419b739dee2503d89c8bf26b3a",
      "ui_metadata":{
         "ui":"kazoo-ui"
      },
      "conference_numbers":[]
   },
   "revision":"6-f79cb73aced09282f4e6a04a858f72e3",
   "request_id":"818a18db7eed440a3e4545509cfeafc6",
   "status":"success",
   "auth_token":"f6330215c035d35c2a44b4dce849a47e"
}

Схема документа конференции¶

Перечень возможных полей json документа описания кофигурации показан ниже

{
    "$schema": "http://json-schema.org/draft-03/schema#",
    "_id": "conferences",
    "description": "Schema for conferences",
    "properties": {
        "conference_numbers": {
            "default": [],
            "description": "Defines conference numbers that can be used by members or moderators",
            "items": {
                "regex": "^\\d+$",
                "required": false,
                "type": "string"
            },
            "required": false,
            "type": "array",
            "uniqueItems": true
        },
        "focus": {
            "description": "This is a read-only property indicating the media server hosting the conference",
            "required": false,
            "type": "string"
        },
        "member": {
            "default": {},
            "description": "Defines the discovery (call in) properties for a member",
            "properties": {
                "join_deaf": {
                    "default": false,
                    "description": "Determines if a member will join deaf",
                    "required": false,
                    "type": "boolean"
                },
                "join_muted": {
                    "default": true,
                    "description": "Determines if a member will join muted",
                    "required": false,
                    "type": "boolean"
                },
                "numbers": {
                    "default": [],
                    "description": "Defines the conference (call in) number(s) for members",
                    "items": {
                        "regex": "^\\d+$",
                        "required": false,
                        "type": "string"
                    },
                    "minItems": 0,
                    "required": false,
                    "type": "array",
                    "uniqueItems": true
                },
                "pins": {
                    "default": [],
                    "description": "Defines the pin number(s) for members",
                    "items": {
                        "regex": "^\\d+$",
                        "required": false,
                        "type": "string"
                    },
                    "required": false,
                    "type": "array"
                }
            },
            "required": false,
            "type": "object"
        },
        "moderator": {
            "default": {},
            "description": "Defines the discovery (call in) properties for a moderator",
            "properties": {
                "join_deaf": {
                    "default": false,
                    "description": "Determines if a moderator will join deaf",
                    "required": false,
                    "type": "boolean"
                },
                "join_muted": {
                    "default": false,
                    "description": "Determines if a moderator will join muted",
                    "required": false,
                    "type": "boolean"
                },
                "numbers": {
                    "default": [],
                    "description": "Defines the conference (call in) number(s) for moderators",
                    "items": {
                        "regex": "^\\d+$",
                        "required": false,
                        "type": "string"
                    },
                    "required": false,
                    "type": "array",
                    "uniqueItems": true
                },
                "pins": {
                    "default": [],
                    "description": "Defines the pin number(s) for moderators",
                    "items": {
                        "regex": "^\\d+$",
                        "required": false,
                        "type": "string"
                    },
                    "required": false,
                    "type": "array"
                }
            },
            "required": false,
            "type": "object"
        },
        "name": {
            "description": "A friendly name for the conference",
            "maxLength": 128,
            "minLength": 1,
            "required": false,
            "type": "string"
        },
        "owner_id": {
            "description": "The user ID who manages this conference",
            "maxLength": 32,
            "minLength": 32,
            "required": false,
            "type": "string"
        },
        "play_name": {
            "default": false,
            "description": "Do we need to announce new conference members?",
            "required": false,
            "type": "boolean"
        },
        "profile": {
            "description": "The XML profile name used to configure the conference",
            "required": false,
            "type": "string"
        }
    },
    "required": false,
    "type": "object"
}

Создание объекта схемы обработки вызова - callflow¶

В данном примере будет показано как создать схему обработки вызова на примере одного действия - вызова обекта конференция. В данном примере конференции назначается номер 3000.

Создание схемы обработки вызова имеет вид

curl -X PUT {api_uri}/accounts/{account_id}/callflows \
     -H 'Content-Type: application/json' \
     -H 'X-Auth-Token: {auth_token}' \
     -d '{"data":{"flow":{"data":{"id":"{conference_id}"},"module":"conference","children":{}},"numbers":["{number}"]}}'

Например:

curl -X PUT https://api.rcsnet.ru/v2/accounts/abcdef1234567890abcdef1234567890/callflows \
     -H 'Content-Type: application/json' \
     -H 'X-Auth-Token: xxxxxxxxxxxxxxxxxxxxxxxxx' \
     -d '{"data":{"flow":{"data":{"id":"68d05c10ef0360f908028d07bfa433e7"},"module":"conference","children":{}},"numbers":["3000"]}}'

В результате будет получен ответ следующего вида

{
   "data":{
      "flow":{
         "data":{
            "id":"68d05c10ef0360f908028d07bfa433e7",
            "moderator":false,
            "play_entry_tone":true,
            "play_exit_tone":true
         },
         "module":"conference",
         "children":{}
      },
      "numbers":[
         "3000"
      ],
      "patterns":[],
      "id":"124df94b976203bcb37e364d292954a3"
   },
   "revision":"1-bb6613a0a52727d001b93fbf9eba37f1",
   "request_id":"4c24585360fab3018bdd53aab7b0bfd5",
   "status":"success",
   "auth_token":"4e8a6ebd9dfffea9d73a4d110e5a8084"
}

Теперь с телефона можно сделать набор номера 3000 и вы войдете в конференицию.

Инициирование вызова телефона сотрудника и соединение его с другим абонентом средствами API¶

Для вызова телефона сотрудника и соедниения его с другим абонентам необходимо выполнить вызов вида:

curl -X GET {api_uri}/accounts/{account_id}/devices/{device_id}/quickcall/{dialed_number} \
     -H 'X-Auth-Token: {auth_token}'

Например ‘device_id’ устройства вы получили выполнив запрос описанный в разделе “Отображение списка SIP устройств”. Для вызова этого устройства и присоединение его в конференцию с номером 3000 необходимо выполнить запрос такого вида.

curl -X GET https://api.rcsnet.ru/v2/accounts/b72e6c95956ed9f061892b58f4d8991c/devices/68a37a5298a40f751b1bd9d12a4e30a8/quickcall/3000 \
     -H 'X-Auth-Token: {auth_token}'

В ответе вы получите описание деталей инициированного вызова следующего вида.

{
   "data":{
      "application_name":"transfer",
      "application_data":{
         "route":" 3000"
      },
      "endpoints":[
         {
            "invite_format":"username",
            "to_user":"2496",
            "to_username":"2496",
            "to_realm":"rcsnet.ru",
            "to_did":"3000",
            "endpoint_id":"68a37a5298a40f751b1bd9d12a4e30a8",
            "codecs":[
               "OPUS",
               "PCMA"
            ],
            "presence_id":"2496@rcsnet.ru",
            "custom_sip_headers":{
               "x_kazoo_aor":"sip:2496@rcsnet.ru"
            },
            "custom_channel_vars":{
               "sip_invite_domain":"rcsnet.ru",
               "media_encryption_enforce_security":false,
               "account_id":"b72e6c95956ed9f061892b58f4d8991c",
               "owner_id":"4a7bad7c80e8d890321492e1ba2d0204",
               "authorizing_type":"device",
               "authorizing_id":"68a37a5298a40f751b1bd9d12a4e30a8",
               "auto_answer":true
            },
            "outbound_call_id":"66b8058e5a6eb9a21176d36cd34a711fa46a-quickcall"
         }
      ],
      "timeout":30,
      "ignore_early_media":true,
      "media":"process",
      "outbound_caller_id_name":"Device QuickCall",
      "outbound_caller_id_number":"2496",
      "outbound_callee_id_name":"Sergey Safarov",
      "outbound_callee_id_number":"3000",
      "dial_endpoint_method":"simultaneous",
      "continue_on_fail":false,
      "custom_channel_vars":{
         "account_id":"b72e6c95956ed9f061892b58f4d8991c",
         "retain_cid":"true",
         "inherit_codec":"false",
         "authorizing_type":"device",
         "authorizing_id":"68a37a5298a40f751b1bd9d12a4e30a8"
      }
   },
   "revision":"54-7fb24d8d0720b2b5471164b0e3601a5e",
   "request_id":"233d4d005c61ddf06d79c06f674330a7",
   "status":"success",
   "auth_token":"bb7b2852827fd3466c023a214b8813ec"
}

В результате выполнения этого вызова на устройство поступит звонок. После того как он будет отвечен будет вызван абонет с номером 3000, в нашем примере этот номер принадлежит конференции. Таким образом сотрудник будет присоеднинен к конференции.

Приложения для иследования API¶

В списке доступных приложений выберите приложение “API explorer”. С помощью данного приожения Вы сможете в интерактивном режиме из браузера выполнить необходимые вам вызовы.

Литератрура¶

Общее описание работы с API находится на странице https://2600hz.atlassian.net/wiki/display/APIs/API+Introduction более подробно API описано в разделе “Configuration APIs” https://2600hz.atlassian.net/wiki/display/APIs/Configuration+APIs.