{"_id":"59393088e376d4002f8a05a2","project":"54eb50e5615ffc1900305a16","version":{"_id":"54eb63b859b1172100334fae","project":"54eb50e5615ffc1900305a16","forked_from":"54eb63a1867e1917009b711d","__v":28,"createdAt":"2015-02-23T17:30:32.501Z","releaseDate":"2015-02-23T17:30:32.501Z","categories":["54eb63b959b1172100334faf","54eb63b959b1172100334fb0","54eb63b959b1172100334fb1","54eb63b959b1172100334fb2","54ed8dd4ab373e2300f50eae","54ed99b2ab373e2300f50ede","55153a6de68daa2f00cff838","551546edbc466623002afe72","5515472ac28d6125001b8884","55154749c28d6125001b8885","555d9b4106dfec0d00d38ea7","5613e06e433e5735007c7708","5624bbb785a31117001c5403","56669e857cc81e0d00253f8e","568b8d837a42220d00498311","56a632277ef6620d00e2f18a","56d8147c3eb4dd0b00201aac","57a9ce2fac6db30e000d7efd","57a9cf4e944ea60e00dc3f74","58172386715dce0f00da4aa0","582dc59ee1b8692300c0dd03","589b19b4fec2730f0082e040","58b04a023529383900a759b5","58b92d1598157a0f004869bf","592e7685c58275000f20174f","59392839e376d4002f8a0474","59393064e376d4002f8a05a1","5947ae0d4005e2000f3a4fec","594a74df1d1de5001ab3517a","5954bc387a147f001b918915","59b8eeeb707542001076d3b6"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1"},"category":{"_id":"59393064e376d4002f8a05a1","project":"54eb50e5615ffc1900305a16","version":"54eb63b859b1172100334fae","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-06-08T11:09:24.273Z","from_sync":false,"order":13,"slug":"voice-calls","title":"Voice calls"},"user":"54eb4fdedf7add210007b29b","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-06-08T11:10:00.408Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"Number Masking service enables two parties to engage in conversation over the phone without exposing their phone numbers to each other. This service is ideal for businesses that share customer information with 3rd parties.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Prerequisites\",\n  \"body\": \"In order to use the Number Masking service the first step is to purchase a number (DID number) which will serve as the connection bridge between two parties. Number masking action needs be set up and then you will be ready to advertise this number to your customers.\\n\\nUse our [Numbers API](/docs/phone-number) or [Customer portal](https://portal.infobip.com/settings/numbers/) to purchase **Voice enabled** phone number.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Number masking workflow\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/6ff8c4f-number-masking.jpg\",\n        \"number-masking.jpg\",\n        1500,\n        879,\n        \"#f3f3f3\"\n      ]\n    }\n  ]\n}\n[/block]\n\nNumber masking setup:\n\n1. [Setup number masking action](#setup-number-masking-action)\n2. [Audio file upload](#audio-file-upload)\n3. [Callback setup](#callback-url-request)\n4. [Status URL setup](#status-url-request)\n\nAdditional methods:\n* [Get number masking action](#get-number-masking-action)\n* [Delete a number masking action](#delete-a-number-masking-action) \n[block:api-header]\n{\n  \"title\": \"Setup number masking action\"\n}\n[/block]\nThis method allows you to setup **CallBack **and **Status **URLs for DID number. \n* CallBack URL is needed in order to get instructions from your side of how to handle incoming calls on a DID number.\nInstructions are result of mapping logic implemented on your side according to your business case.\n * Status URL will be used to deliver status report after the call is finished.\n\n```\nPOST https://api.infobip.com/numbers/1/numbers/{numberKey}/actions\n```\nRequest parameters\n\n\n|Property name|Type|Description|\n|-|-|-|\n|type|string|type of number setup (`VOICE_NUMBER_MASKING`)|\n|callbackUrl|string|Client's URL to call on each number inbound call|\n|statusUrl|string|Client'sURL for status report delivery|\n\n###Request example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /numbers/1/numbers/6FED0BC540BFADD9B05ED7D89AAC22FA/action HTTP/1.1\\nHost: api.infobip.com\\nAuthorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==\\nContent-Type: application/json\\nAccept: application/json\\n\\n{\\n \\\"type\\\" : \\\"VOICE_NUMBER_MASKING\\\",\\n \\\"callbackUrl\\\" : \\\"http://client.server/1/callback\\\",\\n \\\"statusUrl\\\" : \\\"http://client.server/1/status\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nResponse\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"actionKey\\\": \\\"6FED0BC540BFADD9BD89AAC22FA\\\",\\n  \\\"type\\\": \\\"VOICE_NUMBER_MASKING\\\",\\n  \\\"callbackUrl\\\": \\\"http://client.server/1/callback\\\",\\n  \\\"statusUrl\\\": \\\"http://client.server/1/status\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nA successful response is represented by an HTTP status code `200 OK`.\n\n[block:api-header]\n{\n  \"title\": \"Audio file upload\"\n}\n[/block]\nIn some situations you may want to play audio message to the caller instead of forwarding the call to a number from your mapping logic. The audio file should be prerecorded and uploaded to our servers in advance. Audio `fileId` will be returned in the response of the upload request and this `fileId` might be received as a response to the callback URL request (described in the following steps).\n\n```\nPOST https://api.infobip.com/numbers/1/files\n```\n\nRequest parameters\n\n|Property name|Type|Description|\n|-|-|-|\n|url|string|URL of the voice file location. Max size of the file is 4MB. Acceptable file format is mp3|\n|content|string|Byte array of the voice file can be included instead of file URL.|\n \n###Request example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /numbers/1/files HTTP/1.1\\nHost: api.infobip.com\\nAuthorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==\\nContent-Type: application/json\\nAccept: application/json\\n\\n{\\n\\t\\\"url\\\": \\\"http://www.winhistory.de/more/winstart/mp3/winxp.mp3\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nInstead of the file URL, request can contain a byte array of the audio file. In that case, body of the request should look like this:\n\n```\n{\n   \"content\": \"SUQzBAAAAAAAF1RTU0U................oBlRZUxIALUaldwrWAAIoVfL\"\n}\n```\n\n###Response:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"fileId\\\": \\\"382a92df-1f6d-4d30-8274-cf508a0c7d62\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nResponse parameters\n\n|Property name|Type|Description|\n|-|-|-|\n|fileId|string|Id of the uploaded audio file. Id might be used as a Callback response (see next step)|\n[block:api-header]\n{\n  \"title\": \"CallBack URL Request\"\n}\n[/block]\nUpon receiving a call to the DID number from your customer, Infobip's platform will generate a request to `callbackUrl` configured on the number. The request contains the caller number and the DID number. In return, Infobip’s platform expects the phone number to forward the call to and caller id which should be presented.\n\nRequest parameters\n\n|Property name|Type|Description|\n|-|-|-|\n|from|string|Caller number|\n|to|string|Called number|\n\n###Request example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"from\\\": \\\"41793026727\\\",\\n\\t\\\"to\\\": \\\"41793026731\\\"\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n###Response\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"command\\\": \\\"dial\\\",\\n\\t\\\"phoneNumber\\\": \\\"41793026785\\\",\\n\\t\\\"callerId\\\": \\\"41793026700\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nDepending of the use case, the response may contain the audio file id which will be played back to the caller. In that case, the response should look like this:\n\n```\n{\n\t\"command\": \"audio\",\n\t\"fileId\": \"382a92df-1f6d-4d30-8274-cf508a0c7d62\"\n}\n```\n \nResponse parameters\n\n|Property name|Type|Description|\n|-|-|-|\n|command|string|Command description. Values should be `dial` or `audio`|\n|phoneNumber|string|Destination phone number to call|\n|callerId|String|Which callerId should be displayed to callee|\n|fileId|String|File to be played to your customer|\n[block:api-header]\n{\n  \"title\": \"Status URL Request\"\n}\n[/block]\nWhen a call is terminated, Infobip's platform will send a status report to the `statusUrl` that was provided during the setup of the number.\n\n ###Request parameters\n\n|Property name|Type|Description|\n|-|-|-|\n|action|string|configured action (`dial` or `audio`)|\n|from|string|Caller number|\n|to|string|DID number|\n|transferTo|String|Callee (transfer) number|\n|duration|int|Duration of the call|\n|status|String|Status of the call. Could be `answered`, `busy`, `no answer`, `failed` or `congestion`|\n|FileID|String|File that was played to your customer|\n\n###Request example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"action\\\": \\\"dial\\\",\\n  \\\"from\\\": \\\"41793026727\\\",\\n  \\\"to\\\": \\\"41793026731\\\",\\n  \\\"transferTo\\\": \\\"41793026785\\\",\\n  \\\"duration\\\": \\\"235\\\",\\n  \\\"status\\\": \\\"answered\\\"\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nA successful response is represented by an HTTP status code `200 OK` from the Client's platform.\n\n[block:api-header]\n{\n  \"title\": \"Additional APIs\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Get number masking action\"\n}\n[/block]\nThe method will return a masking action setup on a specific number (`numberKey`).\n\n```\nGET https://api.infobip.com/numbers/1/numbers/{numberKey}/actions\n``` \n\n###Request example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /numbers/1/numbers/6FED0BC540BFADD9B05ED7D89AAC22FA/actions HTTP/1.1\\nHost: api.infobip.com\\nAuthorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==\\nAccept: application/json\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n###Response\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"actions\\\": [\\n    {\\n      \\\"actionKey\\\": \\\"6FED0BC540BFADD9BD89AAC22FA\\\",\\n      \\\"type\\\": \\\"VOICE_NUMBER_MASKING\\\",\\n      \\\"callbackUrl\\\": \\\"http://client.server/1/callback\\\",\\n      \\\"statusUrl\\\": \\\"http://client.server/1/status\\\"\\n    }\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Delete a number masking action\"\n}\n[/block]\nThis method will delete a single number masking action (`actionKey`) on a number (`numberKey`).\n\n```\nDELETE https://api.infobip.com/numbers/1/numbers/{numberKey}/actions/{actionKey}\n``` \n\n###Request example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"DELETE /numbers/1/numbers/6FED0BC540BFADD9B05ED7D89AAC22FA/actions/6FED0BC540BFADD9BD89AAC22FA HTTP/1.1\\nHost: api.infobip.com\\nAuthorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==\\nAccept: application/json\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nA successful response is presented by an HTTP status code `204 No Content`. There is no response body.","excerpt":"Connect two parties over a voice call without exposing their real phone numbers.","slug":"number-masking","type":"basic","title":"Number masking"}

Number masking

Connect two parties over a voice call without exposing their real phone numbers.

Number Masking service enables two parties to engage in conversation over the phone without exposing their phone numbers to each other. This service is ideal for businesses that share customer information with 3rd parties. [block:callout] { "type": "info", "title": "Prerequisites", "body": "In order to use the Number Masking service the first step is to purchase a number (DID number) which will serve as the connection bridge between two parties. Number masking action needs be set up and then you will be ready to advertise this number to your customers.\n\nUse our [Numbers API](/docs/phone-number) or [Customer portal](https://portal.infobip.com/settings/numbers/) to purchase **Voice enabled** phone number." } [/block] [block:api-header] { "title": "Number masking workflow" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/6ff8c4f-number-masking.jpg", "number-masking.jpg", 1500, 879, "#f3f3f3" ] } ] } [/block] Number masking setup: 1. [Setup number masking action](#setup-number-masking-action) 2. [Audio file upload](#audio-file-upload) 3. [Callback setup](#callback-url-request) 4. [Status URL setup](#status-url-request) Additional methods: * [Get number masking action](#get-number-masking-action) * [Delete a number masking action](#delete-a-number-masking-action) [block:api-header] { "title": "Setup number masking action" } [/block] This method allows you to setup **CallBack **and **Status **URLs for DID number. * CallBack URL is needed in order to get instructions from your side of how to handle incoming calls on a DID number. Instructions are result of mapping logic implemented on your side according to your business case. * Status URL will be used to deliver status report after the call is finished. ``` POST https://api.infobip.com/numbers/1/numbers/{numberKey}/actions ``` Request parameters |Property name|Type|Description| |-|-|-| |type|string|type of number setup (`VOICE_NUMBER_MASKING`)| |callbackUrl|string|Client's URL to call on each number inbound call| |statusUrl|string|Client'sURL for status report delivery| ###Request example [block:code] { "codes": [ { "code": "POST /numbers/1/numbers/6FED0BC540BFADD9B05ED7D89AAC22FA/action HTTP/1.1\nHost: api.infobip.com\nAuthorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==\nContent-Type: application/json\nAccept: application/json\n\n{\n \"type\" : \"VOICE_NUMBER_MASKING\",\n \"callbackUrl\" : \"http://client.server/1/callback\",\n \"statusUrl\" : \"http://client.server/1/status\"\n}", "language": "json" } ] } [/block] Response [block:code] { "codes": [ { "code": "{\n \"actionKey\": \"6FED0BC540BFADD9BD89AAC22FA\",\n \"type\": \"VOICE_NUMBER_MASKING\",\n \"callbackUrl\": \"http://client.server/1/callback\",\n \"statusUrl\": \"http://client.server/1/status\"\n}", "language": "json" } ] } [/block] A successful response is represented by an HTTP status code `200 OK`. [block:api-header] { "title": "Audio file upload" } [/block] In some situations you may want to play audio message to the caller instead of forwarding the call to a number from your mapping logic. The audio file should be prerecorded and uploaded to our servers in advance. Audio `fileId` will be returned in the response of the upload request and this `fileId` might be received as a response to the callback URL request (described in the following steps). ``` POST https://api.infobip.com/numbers/1/files ``` Request parameters |Property name|Type|Description| |-|-|-| |url|string|URL of the voice file location. Max size of the file is 4MB. Acceptable file format is mp3| |content|string|Byte array of the voice file can be included instead of file URL.| ###Request example: [block:code] { "codes": [ { "code": "POST /numbers/1/files HTTP/1.1\nHost: api.infobip.com\nAuthorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==\nContent-Type: application/json\nAccept: application/json\n\n{\n\t\"url\": \"http://www.winhistory.de/more/winstart/mp3/winxp.mp3\"\n}", "language": "json" } ] } [/block] Instead of the file URL, request can contain a byte array of the audio file. In that case, body of the request should look like this: ``` { "content": "SUQzBAAAAAAAF1RTU0U................oBlRZUxIALUaldwrWAAIoVfL" } ``` ###Response: [block:code] { "codes": [ { "code": "{\n \"fileId\": \"382a92df-1f6d-4d30-8274-cf508a0c7d62\"\n}", "language": "json" } ] } [/block] Response parameters |Property name|Type|Description| |-|-|-| |fileId|string|Id of the uploaded audio file. Id might be used as a Callback response (see next step)| [block:api-header] { "title": "CallBack URL Request" } [/block] Upon receiving a call to the DID number from your customer, Infobip's platform will generate a request to `callbackUrl` configured on the number. The request contains the caller number and the DID number. In return, Infobip’s platform expects the phone number to forward the call to and caller id which should be presented. Request parameters |Property name|Type|Description| |-|-|-| |from|string|Caller number| |to|string|Called number| ###Request example [block:code] { "codes": [ { "code": "{\n\t\"from\": \"41793026727\",\n\t\"to\": \"41793026731\"\n}\n", "language": "json" } ] } [/block] ###Response [block:code] { "codes": [ { "code": "{\n\t\"command\": \"dial\",\n\t\"phoneNumber\": \"41793026785\",\n\t\"callerId\": \"41793026700\"\n}", "language": "json" } ] } [/block] Depending of the use case, the response may contain the audio file id which will be played back to the caller. In that case, the response should look like this: ``` { "command": "audio", "fileId": "382a92df-1f6d-4d30-8274-cf508a0c7d62" } ``` Response parameters |Property name|Type|Description| |-|-|-| |command|string|Command description. Values should be `dial` or `audio`| |phoneNumber|string|Destination phone number to call| |callerId|String|Which callerId should be displayed to callee| |fileId|String|File to be played to your customer| [block:api-header] { "title": "Status URL Request" } [/block] When a call is terminated, Infobip's platform will send a status report to the `statusUrl` that was provided during the setup of the number. ###Request parameters |Property name|Type|Description| |-|-|-| |action|string|configured action (`dial` or `audio`)| |from|string|Caller number| |to|string|DID number| |transferTo|String|Callee (transfer) number| |duration|int|Duration of the call| |status|String|Status of the call. Could be `answered`, `busy`, `no answer`, `failed` or `congestion`| |FileID|String|File that was played to your customer| ###Request example: [block:code] { "codes": [ { "code": "{\n \"action\": \"dial\",\n \"from\": \"41793026727\",\n \"to\": \"41793026731\",\n \"transferTo\": \"41793026785\",\n \"duration\": \"235\",\n \"status\": \"answered\"\n}\n", "language": "json" } ] } [/block] A successful response is represented by an HTTP status code `200 OK` from the Client's platform. [block:api-header] { "title": "Additional APIs" } [/block] [block:api-header] { "title": "Get number masking action" } [/block] The method will return a masking action setup on a specific number (`numberKey`). ``` GET https://api.infobip.com/numbers/1/numbers/{numberKey}/actions ``` ###Request example [block:code] { "codes": [ { "code": "GET /numbers/1/numbers/6FED0BC540BFADD9B05ED7D89AAC22FA/actions HTTP/1.1\nHost: api.infobip.com\nAuthorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==\nAccept: application/json", "language": "json" } ] } [/block] ###Response [block:code] { "codes": [ { "code": "{\n \"actions\": [\n {\n \"actionKey\": \"6FED0BC540BFADD9BD89AAC22FA\",\n \"type\": \"VOICE_NUMBER_MASKING\",\n \"callbackUrl\": \"http://client.server/1/callback\",\n \"statusUrl\": \"http://client.server/1/status\"\n }\n ]\n}", "language": "json" } ] } [/block] [block:api-header] { "title": "Delete a number masking action" } [/block] This method will delete a single number masking action (`actionKey`) on a number (`numberKey`). ``` DELETE https://api.infobip.com/numbers/1/numbers/{numberKey}/actions/{actionKey} ``` ###Request example [block:code] { "codes": [ { "code": "DELETE /numbers/1/numbers/6FED0BC540BFADD9B05ED7D89AAC22FA/actions/6FED0BC540BFADD9BD89AAC22FA HTTP/1.1\nHost: api.infobip.com\nAuthorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==\nAccept: application/json", "language": "json" } ] } [/block] A successful response is presented by an HTTP status code `204 No Content`. There is no response body.