{"_id":"58a68f4bfc922d0f00ce8363","category":{"_id":"58a68ebf3239fa0f00857619","project":"55c8cff571d7580d0063a5e5","__v":0,"version":"57624356653c2d2200fec79c","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-02-17T05:48:47.118Z","from_sync":false,"order":9,"slug":"account-listeners","title":"Account Event Listeners"},"githubsync":"","project":"55c8cff571d7580d0063a5e5","user":"56f99ab84d2b4f3400edb636","version":{"_id":"57624356653c2d2200fec79c","__v":22,"project":"55c8cff571d7580d0063a5e5","createdAt":"2016-06-16T06:12:38.244Z","releaseDate":"2016-06-16T06:12:38.244Z","categories":["57624356653c2d2200fec79d","57624356653c2d2200fec79e","57624356653c2d2200fec79f","57624356653c2d2200fec7a0","57624356653c2d2200fec7a1","57624356653c2d2200fec7a2","57624356653c2d2200fec7a3","57624356653c2d2200fec7a4","57624356653c2d2200fec7a5","57624356653c2d2200fec7a6","57624356653c2d2200fec7a7","57624356653c2d2200fec7a8","57624356653c2d2200fec7a9","57624356653c2d2200fec7aa","5779ca1b99b40b0e005abb3a","5779d198aea88b0e00f63277","5797d3ab17ced017003c4be4","57ac170ef1cdae0e0053cdfc","57dbfc723ed3450e00dc9e6d","5804d12d16161c0f0077df9b","5841064b652e5b0f0015a7c8","588b5e5f2966b2230009cbf9","58a68ebf3239fa0f00857619","58c23c8b4922930f0050ac91","58fd1460809fc30f00f2ee07","5934eaf5328680002d77de6a","594bf91601cfe6000f40f4c5","595c4ed696b447001ba0cf6d","596524495cee50001575f5be","5970d4f1313162004dd303b5","59780fac24dbd1001a1fa057","59a8cfd3ead78a002d63cafe","59e0323d93da1f001c9ec170","5b0c16f2be9fcb0003e28222","5ba8fd1a4c8c220003a08f0f"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"4.0.0","version":"4"},"__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-02-17T05:51:07.333Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Note: This API is for users with Account Owner scope access token. Users with Extension User scope token should invoke the Extension level Listeners API with the following definition:\\n\\nhttps://api.phone.com/v4/accounts/:account_id/extensions/:extension_id/listeners\"\n}\n[/block]\nAt the heart of every telephony system is the Events Engine.  At Phone.com, our customers (and their call traffic) emit millions of events per day.  These events play a key role in advanced integration opportunities such as CRM integration, security/auditing, and real-time contextual call control.\n\nThe [Events](doc:account-events) and Listeners API Services aim to simplify and standardize the method in which events are extracted from our systems and processed.  These services provide consistent interfaces for internal systems to log events, manage subscriptions, and provide interfaces for external systems (e.g. customer applications or integrations such as Salesforce CRM) to subscribe to account-specific events and manage the subscriptions.\n\nAs of today, Phone.com supports the following events.  More events will be added as we continue to upgrade our phone services.  Reference to the [Events API](doc:account-events) for details.\n\n    - call.new\n    - call.update \n    - call.complete  \n    - call.log\n    - sms.in\n    - sms.out\n\nThe \"call\" events help customers know when a call starts, when the callee answers the call, when a call ends and when a call entry is recorded and ready for retrieval. The \"sms\" events help customers know when a sms is sent or received.  This provides enough information for applications such as Incoming Call / SMS Notification and others to improve productivities.  More events will be added once we understand more about customer needs.\n\nThe Listeners service provides an interface for internal and external applications to subscribe to events.  Listeners can be added by customers to their Phone.com account using the Phoenix API.  A listener sets up an event type and a callback URL, when the event is emitted, it will be forwarded to the URL.  For example, a call.new event may be setup with a callback URL http://newcall.phone.com, when an inbound call comes in, the event with all the call info (payload) will be forwarded to http://newcall.phone.com.\n\nThe following are the supported Listener services:\n\n## Supported Services\n* [List Listeners](doc:list-account-listeners) \n* [Create Listener](doc:create-account-listener)  \n* [Get Listener](doc:get-account-listener) \n* [Replace Listener](doc:replace-account-listener) \n* [Delete Listener](doc:delete-account-listener) \n\n## Listener Object\nThe Listener Object is used to represent a listener.  Here are the properties:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"\",\n    \"0-0\": \"`id`\",\n    \"0-1\": \"Integer ID. Read-only.\",\n    \"0-2\": \"\",\n    \"1-0\": \"`type`\",\n    \"1-1\": \"Type of listener: callback\",\n    \"1-2\": \"\",\n    \"2-0\": \"'event_type'\",\n    \"2-1\": \"Type of event subscribed by the listener:\\n\\ncall.new, call.update, call.complete, call.log,\\nsms.in, sms.out\",\n    \"3-0\": \"'callbacks'\",\n    \"3-1\": \"Array of Callback Object\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n## Callback Object\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"'url'\",\n    \"0-1\": \"URL of webhook, where the event is emitted to\\n\\nNote:  The listener supports both HTTP & HTTPS, we highly recommend that users use HTTPS on all callbacks (with user name and password) to ensure no one may send malicious events pretending to be Phone.com.\",\n    \"1-0\": \"'role'\",\n    \"1-1\": \"Role of callback: main or backup\",\n    \"2-0\": \"'verb'\",\n    \"2-1\": \"HTTP method: get or post\",\n    \"3-0\": \"'username'\",\n    \"3-1\": \"Optional user name needed to logon to the webhook URL\",\n    \"4-0\": \"'password'\",\n    \"4-1\": \"Optional password needed to logon to the webhook URL\",\n    \"5-0\": \"'timeout'\",\n    \"5-1\": \"Optional : Duration of HTTP response will time out while sending the event to the callback URL.\\n(1 - 10 seconds)\"\n  },\n  \"cols\": 2,\n  \"rows\": 6\n}\n[/block]\nHere is an example of a listener object:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\": 13,\\n    \\\"type\\\": \\\"callback\\\",\\n    \\\"event\\\": \\\"call.update\\\",\\n    \\\"callbacks\\\": [\\n        {\\n            \\\"url\\\": \\\"https://requestb.in/10eabcde\\\",\\n            \\\"role\\\": \\\"main\\\",\\n            \\\"verb\\\": \\\"POST\\\",\\n            \\\"username\\\": \\\"123\\\",\\n            \\\"password\\\": \\\"************\\\",\\n            \\\"timeout\\\": 10\\n        }\\n    ],\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\"\n}\n[/block]","excerpt":"Call and SMS Event Listeners","slug":"account-listeners","type":"basic","title":"Event Listeners"}

Event Listeners

Call and SMS Event Listeners

[block:callout] { "type": "info", "body": "Note: This API is for users with Account Owner scope access token. Users with Extension User scope token should invoke the Extension level Listeners API with the following definition:\n\nhttps://api.phone.com/v4/accounts/:account_id/extensions/:extension_id/listeners" } [/block] At the heart of every telephony system is the Events Engine. At Phone.com, our customers (and their call traffic) emit millions of events per day. These events play a key role in advanced integration opportunities such as CRM integration, security/auditing, and real-time contextual call control. The [Events](doc:account-events) and Listeners API Services aim to simplify and standardize the method in which events are extracted from our systems and processed. These services provide consistent interfaces for internal systems to log events, manage subscriptions, and provide interfaces for external systems (e.g. customer applications or integrations such as Salesforce CRM) to subscribe to account-specific events and manage the subscriptions. As of today, Phone.com supports the following events. More events will be added as we continue to upgrade our phone services. Reference to the [Events API](doc:account-events) for details. - call.new - call.update - call.complete - call.log - sms.in - sms.out The "call" events help customers know when a call starts, when the callee answers the call, when a call ends and when a call entry is recorded and ready for retrieval. The "sms" events help customers know when a sms is sent or received. This provides enough information for applications such as Incoming Call / SMS Notification and others to improve productivities. More events will be added once we understand more about customer needs. The Listeners service provides an interface for internal and external applications to subscribe to events. Listeners can be added by customers to their Phone.com account using the Phoenix API. A listener sets up an event type and a callback URL, when the event is emitted, it will be forwarded to the URL. For example, a call.new event may be setup with a callback URL http://newcall.phone.com, when an inbound call comes in, the event with all the call info (payload) will be forwarded to http://newcall.phone.com. The following are the supported Listener services: ## Supported Services * [List Listeners](doc:list-account-listeners) * [Create Listener](doc:create-account-listener) * [Get Listener](doc:get-account-listener) * [Replace Listener](doc:replace-account-listener) * [Delete Listener](doc:delete-account-listener) ## Listener Object The Listener Object is used to represent a listener. Here are the properties: [block:parameters] { "data": { "h-0": "Property", "h-1": "Description", "h-2": "", "0-0": "`id`", "0-1": "Integer ID. Read-only.", "0-2": "", "1-0": "`type`", "1-1": "Type of listener: callback", "1-2": "", "2-0": "'event_type'", "2-1": "Type of event subscribed by the listener:\n\ncall.new, call.update, call.complete, call.log,\nsms.in, sms.out", "3-0": "'callbacks'", "3-1": "Array of Callback Object" }, "cols": 2, "rows": 4 } [/block] ## Callback Object [block:parameters] { "data": { "h-0": "Property", "h-1": "Description", "0-0": "'url'", "0-1": "URL of webhook, where the event is emitted to\n\nNote: The listener supports both HTTP & HTTPS, we highly recommend that users use HTTPS on all callbacks (with user name and password) to ensure no one may send malicious events pretending to be Phone.com.", "1-0": "'role'", "1-1": "Role of callback: main or backup", "2-0": "'verb'", "2-1": "HTTP method: get or post", "3-0": "'username'", "3-1": "Optional user name needed to logon to the webhook URL", "4-0": "'password'", "4-1": "Optional password needed to logon to the webhook URL", "5-0": "'timeout'", "5-1": "Optional : Duration of HTTP response will time out while sending the event to the callback URL.\n(1 - 10 seconds)" }, "cols": 2, "rows": 6 } [/block] Here is an example of a listener object: [block:code] { "codes": [ { "code": "{\n \"id\": 13,\n \"type\": \"callback\",\n \"event\": \"call.update\",\n \"callbacks\": [\n {\n \"url\": \"https://requestb.in/10eabcde\",\n \"role\": \"main\",\n \"verb\": \"POST\",\n \"username\": \"123\",\n \"password\": \"************\",\n \"timeout\": 10\n }\n ],\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic" } [/block]