{"_id":"5b0c175ab7985e000307061f","project":"55c8cff571d7580d0063a5e5","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"},"category":{"_id":"5b0c16f2be9fcb0003e28222","project":"55c8cff571d7580d0063a5e5","version":"57624356653c2d2200fec79c","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2018-05-28T14:49:22.366Z","from_sync":false,"order":10,"slug":"events","title":"Account Events"},"user":"56f99ab84d2b4f3400edb636","githubsync":"","__v":0,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-05-28T14:51:06.916Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","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 Events API with the following definition:\\n\\nhttps://api.phone.com/v4/accounts/:account_id/extensions/:extension_id/events\"\n}\n[/block]\nAt the heart of every telephony system is the Events Engine.  At Phone.com, our customers (and their call/sms 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 and [Listeners](doc:account-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\nFor detail description of the Event Listeners API, reference to this [link](doc:account-listeners).\n\nAs of today, Phone.com supports the following events.  More events will be added as we continue to upgrade our phone services.\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\n\n\nThe following are the supported Event services:\n\n## Supported Services\n* [List Events](doc:list-account-events) \n* [Get Event](doc:get-account-event) \n\n## Event Object\nThe Event Object is used to represent an event.  Here are the properties:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`id`\",\n    \"0-1\": \"Event ID (Integer ID, read-only).\",\n    \"1-0\": \"`voip_id`\",\n    \"1-1\": \"Account API ID\",\n    \"2-0\": \"`type`\",\n    \"2-1\": \"call.new, call.update, call.complete, call.log, sms.in or sms.out\",\n    \"3-0\": \"`timestamp`\",\n    \"3-1\": \"Unix timestamp, representing the time when the event is emitted\",\n    \"4-0\": \"`extension`\",\n    \"4-1\": \"Account extension ID when the event is associated with an extension.  Null if event is at account level\",\n    \"5-0\": \"`payload`\",\n    \"5-1\": \"Event Payload Type Object\"\n  },\n  \"cols\": 2,\n  \"rows\": 6\n}\n[/block]\n## Event Payload Type Object\n\nEvent payload is the information used to describe the details of an event.  Payload format varies based on the type of event associated with it.  Below are payload examples for each event type:\n\n\nThe call.new event with the following payload is emitted to the listener webhook URL when an incoming call starts. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\": 1765963,\\n    \\\"voip_id\\\": 349033,\\n    \\\"type\\\": \\\"call.new\\\",\\n    \\\"timestamp\\\": \\\"1527472973.0000\\\",\\n    \\\"extension\\\": null,\\n    \\\"payload\\\": {\\n        \\\"call_id\\\": \\\"1f10d44e-4ea0-4c60-92ab-91ebca4522b8\\\",\\n        \\\"direction\\\": \\\"in\\\",\\n        \\\"state\\\": \\\"connecting\\\",\\n        \\\"from_did\\\": \\\"+12012206269\\\",\\n        \\\"to_did\\\": \\\"+12014312904\\\"\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Event call.new\"\n    }\n  ]\n}\n[/block]\nThe call.update event with the following payload is emitted to the listener webhook URL when the phone rings.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"call.update event for IP Phones with multiple lines\",\n  \"body\": \"The field to_sip_uri contains sip info in the format of sip:nnnnn:::at:::sip.phone.com where nnnnn is the device id of the IP Phone.  For IP Phones which supports multiple lines, the format for each line is <p>\\n&nbsp;&nbsp;&nbsp;&nbsp;sip:nnnnn@sip.phone.com (Line 1)\\n&nbsp;&nbsp;&nbsp;&nbsp;sip:nnnnnx2@sip.phone.com (Line 2)\\n&nbsp;&nbsp;&nbsp;&nbsp;sip:nnnnnx3@sip.phone.com (Line 3)\\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; :\\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; :\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\": 1765963,\\n    \\\"voip_id\\\": 349033,\\n    \\\"type\\\": \\\"call.update\\\",\\n    \\\"timestamp\\\": \\\"1527472973.0000\\\",\\n    \\\"extension\\\": null,\\n    \\\"payload\\\": {\\n        \\\"call_id\\\": \\\"c131037b-3de4-484d-87c2-84c9a953e8a9\\\",\\n        \\\"direction\\\": \\\"in\\\",\\n        \\\"state\\\": \\\"connected\\\",\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Event call.update\"\n    }\n  ]\n}\n[/block]\nThe call.update event with the following payload is emitted to the listener webhook URL when the callee answers.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\": 1787663,\\n    \\\"voip_id\\\": 349033,\\n    \\\"type\\\": \\\"call.update\\\",\\n    \\\"timestamp\\\": \\\"1487344385.0000\\\",\\n    \\\"extension\\\": 5228,\\n    \\\"payload\\\": {\\n        \\\"call_id\\\": \\\"82e0a6e4-929c-48d1-9af0-fb0ce3c744bd\\\",\\n        \\\"direction\\\": \\\"in\\\",\\n        \\\"state\\\": \\\"connected\\\",\\n        \\\"from_did\\\": \\\"+17329910133\\\",\\n        \\\"from_cid\\\": \\\"Phone.com\\\",\\n        \\\"to_sip_uri\\\": \\\"sip:95276@sip.phone.com\\\"\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Event call.update \"\n    }\n  ]\n}\n[/block]\nThe call.complete event with the following payload is emitted to the listener webhook URL when the call is hanged up by either caller or callee.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\": 1787688,\\n    \\\"voip_id\\\": 349033,\\n    \\\"type\\\": \\\"call.complete\\\",\\n    \\\"timestamp\\\": \\\"1487344385.0000\\\",\\n    \\\"extension\\\": 5228,\\n    \\\"payload\\\": {\\n        \\\"call_id\\\": \\\"82e0a6e4-929c-48d1-9af0-fb0ce3c744bd\\\",\\n        \\\"direction\\\": \\\"in\\\",\\n        \\\"state\\\": \\\"completed\\\",\\n        \\\"completion_state\\\": \\\"success\\\",\\n        \\\"started_at\\\": \\\"1487344363.3829\\\",\\n        \\\"connected_at\\\": \\\"1487344385.4029\\\",\\n        \\\"completed_at\\\": \\\"1487344386.0454\\\",\\n        \\\"duration\\\": 1,\\n        \\\"from_did\\\": \\\"+17329910133\\\",\\n        \\\"to_did\\\": \\\"+12014840200\\\",\\n        \\\"from_cid\\\": \\\"+17329910133\\\"\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Event call.complete\"\n    }\n  ]\n}\n[/block]\nThe call.log event with the following payload is emitted to the listener webhook URL when the call is saved into the Phone.com system.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\": 1965623,\\n    \\\"voip_id\\\": 349033,\\n    \\\"type\\\": \\\"call.log\\\",\\n    \\\"timestamp\\\": \\\"1487344399.0000\\\",\\n    \\\"extension\\\": 5228,\\n    \\\"payload\\\": {\\n        \\\"call_id\\\": \\\"82e0a6e4-929c-48d1-9af0-fb0ce3c744bd\\\"\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Event call.log\"\n    }\n  ]\n}\n[/block]\nThe sms.in event with the following payload is emitted to the listener webhook URL when an incoming sms has arrived.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\": 3791,\\n    \\\"voip_id\\\": 349033,\\n    \\\"type\\\": \\\"sms.in\\\",\\n    \\\"timestamp\\\": 1489121926,\\n    \\\"extension\\\": 267035,\\n    \\\"payload\\\": {\\n        \\\"sms_id\\\": \\\"58c232863d1c04105a8b456d\\\",\\n        \\\"to_did\\\": \\\"+18582526745\\\",\\n        \\\"from_did\\\": \\\"+18582524164\\\",\\n        \\\"message\\\": \\\"We support international characters \\\\u4e00\\\\u4e8c\\\\u4e09\\\\u56db\\\\u4e94\\\"\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Event sms.in\"\n    }\n  ]\n}\n[/block]\nThe sms.out event with the following payload is emitted to the listener webhook URL when an outgoing sms is delivered.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\": 3787,\\n    \\\"voip_id\\\": 349033,\\n    \\\"type\\\": \\\"sms.out\\\",\\n    \\\"timestamp\\\": 1489121758,\\n    \\\"extension\\\": 267035,\\n    \\\"payload\\\": {\\n        \\\"sms_id\\\": \\\"58c231df3d1c04135a8b456f\\\",\\n        \\\"to_did\\\": \\\"+17329910133\\\",\\n        \\\"from_did\\\": \\\"+18582524164\\\",\\n        \\\"message\\\": \\\"List of emojis \\\\ud83d\\\\udc34\\\\ud83d\\\\udc12\\\\ud83d\\\\udc34\\\\ud83e\\\\udd81\\\"\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Event sms.out\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\"\n}\n[/block]","excerpt":"Call and SMS Events","slug":"account-events","type":"basic","title":"Events"}

Events

Call and SMS Events

[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 Events API with the following definition:\n\nhttps://api.phone.com/v4/accounts/:account_id/extensions/:extension_id/events" } [/block] At the heart of every telephony system is the Events Engine. At Phone.com, our customers (and their call/sms 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 and [Listeners](doc:account-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. For detail description of the Event Listeners API, reference to this [link](doc:account-listeners). As of today, Phone.com supports the following events. More events will be added as we continue to upgrade our phone services. - 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 following are the supported Event services: ## Supported Services * [List Events](doc:list-account-events) * [Get Event](doc:get-account-event) ## Event Object The Event Object is used to represent an event. Here are the properties: [block:parameters] { "data": { "h-0": "Property", "h-1": "Description", "0-0": "`id`", "0-1": "Event ID (Integer ID, read-only).", "1-0": "`voip_id`", "1-1": "Account API ID", "2-0": "`type`", "2-1": "call.new, call.update, call.complete, call.log, sms.in or sms.out", "3-0": "`timestamp`", "3-1": "Unix timestamp, representing the time when the event is emitted", "4-0": "`extension`", "4-1": "Account extension ID when the event is associated with an extension. Null if event is at account level", "5-0": "`payload`", "5-1": "Event Payload Type Object" }, "cols": 2, "rows": 6 } [/block] ## Event Payload Type Object Event payload is the information used to describe the details of an event. Payload format varies based on the type of event associated with it. Below are payload examples for each event type: The call.new event with the following payload is emitted to the listener webhook URL when an incoming call starts. [block:code] { "codes": [ { "code": "{\n \"id\": 1765963,\n \"voip_id\": 349033,\n \"type\": \"call.new\",\n \"timestamp\": \"1527472973.0000\",\n \"extension\": null,\n \"payload\": {\n \"call_id\": \"1f10d44e-4ea0-4c60-92ab-91ebca4522b8\",\n \"direction\": \"in\",\n \"state\": \"connecting\",\n \"from_did\": \"+12012206269\",\n \"to_did\": \"+12014312904\"\n }\n}", "language": "json", "name": "Event call.new" } ] } [/block] The call.update event with the following payload is emitted to the listener webhook URL when the phone rings. [block:callout] { "type": "success", "title": "call.update event for IP Phones with multiple lines", "body": "The field to_sip_uri contains sip info in the format of sip:nnnnn@sip.phone.com where nnnnn is the device id of the IP Phone. For IP Phones which supports multiple lines, the format for each line is <p>\n&nbsp;&nbsp;&nbsp;&nbsp;sip:nnnnn@sip.phone.com (Line 1)\n&nbsp;&nbsp;&nbsp;&nbsp;sip:nnnnnx2@sip.phone.com (Line 2)\n&nbsp;&nbsp;&nbsp;&nbsp;sip:nnnnnx3@sip.phone.com (Line 3)\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; :\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; :" } [/block] [block:code] { "codes": [ { "code": "{\n \"id\": 1765963,\n \"voip_id\": 349033,\n \"type\": \"call.update\",\n \"timestamp\": \"1527472973.0000\",\n \"extension\": null,\n \"payload\": {\n \"call_id\": \"c131037b-3de4-484d-87c2-84c9a953e8a9\",\n \"direction\": \"in\",\n \"state\": \"connected\",\n }\n}", "language": "json", "name": "Event call.update" } ] } [/block] The call.update event with the following payload is emitted to the listener webhook URL when the callee answers. [block:code] { "codes": [ { "code": "{\n \"id\": 1787663,\n \"voip_id\": 349033,\n \"type\": \"call.update\",\n \"timestamp\": \"1487344385.0000\",\n \"extension\": 5228,\n \"payload\": {\n \"call_id\": \"82e0a6e4-929c-48d1-9af0-fb0ce3c744bd\",\n \"direction\": \"in\",\n \"state\": \"connected\",\n \"from_did\": \"+17329910133\",\n \"from_cid\": \"Phone.com\",\n \"to_sip_uri\": \"sip:95276@sip.phone.com\"\n }\n}", "language": "json", "name": "Event call.update " } ] } [/block] The call.complete event with the following payload is emitted to the listener webhook URL when the call is hanged up by either caller or callee. [block:code] { "codes": [ { "code": "{\n \"id\": 1787688,\n \"voip_id\": 349033,\n \"type\": \"call.complete\",\n \"timestamp\": \"1487344385.0000\",\n \"extension\": 5228,\n \"payload\": {\n \"call_id\": \"82e0a6e4-929c-48d1-9af0-fb0ce3c744bd\",\n \"direction\": \"in\",\n \"state\": \"completed\",\n \"completion_state\": \"success\",\n \"started_at\": \"1487344363.3829\",\n \"connected_at\": \"1487344385.4029\",\n \"completed_at\": \"1487344386.0454\",\n \"duration\": 1,\n \"from_did\": \"+17329910133\",\n \"to_did\": \"+12014840200\",\n \"from_cid\": \"+17329910133\"\n }\n}", "language": "json", "name": "Event call.complete" } ] } [/block] The call.log event with the following payload is emitted to the listener webhook URL when the call is saved into the Phone.com system. [block:code] { "codes": [ { "code": "{\n \"id\": 1965623,\n \"voip_id\": 349033,\n \"type\": \"call.log\",\n \"timestamp\": \"1487344399.0000\",\n \"extension\": 5228,\n \"payload\": {\n \"call_id\": \"82e0a6e4-929c-48d1-9af0-fb0ce3c744bd\"\n }\n}", "language": "json", "name": "Event call.log" } ] } [/block] The sms.in event with the following payload is emitted to the listener webhook URL when an incoming sms has arrived. [block:code] { "codes": [ { "code": "{\n \"id\": 3791,\n \"voip_id\": 349033,\n \"type\": \"sms.in\",\n \"timestamp\": 1489121926,\n \"extension\": 267035,\n \"payload\": {\n \"sms_id\": \"58c232863d1c04105a8b456d\",\n \"to_did\": \"+18582526745\",\n \"from_did\": \"+18582524164\",\n \"message\": \"We support international characters \\u4e00\\u4e8c\\u4e09\\u56db\\u4e94\"\n }\n}", "language": "json", "name": "Event sms.in" } ] } [/block] The sms.out event with the following payload is emitted to the listener webhook URL when an outgoing sms is delivered. [block:code] { "codes": [ { "code": "{\n \"id\": 3787,\n \"voip_id\": 349033,\n \"type\": \"sms.out\",\n \"timestamp\": 1489121758,\n \"extension\": 267035,\n \"payload\": {\n \"sms_id\": \"58c231df3d1c04135a8b456f\",\n \"to_did\": \"+17329910133\",\n \"from_did\": \"+18582524164\",\n \"message\": \"List of emojis \\ud83d\\udc34\\ud83d\\udc12\\ud83d\\udc34\\ud83e\\udd81\"\n }\n}", "language": "json", "name": "Event sms.out" } ] } [/block] [block:api-header] { "type": "basic" } [/block]