### GET /api/v2/company (Production) Source: https://developers.dialpad.com/docs/authentication-basics Example of how to authenticate a GET request to retrieve company information in the production environment using a bearer token. ```APIDOC ## GET /api/v2/company (Production) ### Description Authenticates a GET request to the company endpoint in the production environment using an access token as a bearer token. ### Method GET ### Endpoint `https://dialpad.com/api/v2/company/` ### Parameters #### Headers - **Accept** (string) - Required - `application/json` - **Authorization** (string) - Required - `Bearer $accessToken` ### Request Example ```curl curl --request GET \ --url 'https://dialpad.com/api/v2/company/' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $accessToken' ``` ### Response #### Success Response (200) - **(structure varies)** - The response will contain company details. #### Response Example ```json { "example": "response body" } ``` ``` -------------------------------- ### GET /api/v2/company (Sandbox) Source: https://developers.dialpad.com/docs/authentication-basics Example of how to authenticate a GET request to retrieve company information in the Dialpad sandbox environment using a bearer token. ```APIDOC ## GET /api/v2/company (Sandbox) ### Description Authenticates a GET request to the company endpoint in the sandbox environment using an access token as a bearer token. ### Method GET ### Endpoint `https://sandbox.dialpad.com/api/v2/company/` ### Parameters #### Headers - **Accept** (string) - Required - `application/json` - **Authorization** (string) - Required - `Bearer $accessToken` ### Request Example ```curl curl --request GET \ --url 'https://sandbox.dialpad.com/api/v2/company/' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $accessToken' ``` ### Response #### Success Response (200) - **(structure varies)** - The response will contain company details. #### Response Example ```json { "example": "response body" } ``` ``` -------------------------------- ### GET /api/v2/company (URL Parameter) Source: https://developers.dialpad.com/docs/authentication-basics Example of using an API key as a URL parameter for the company endpoint. This method is not recommended due to security concerns. ```APIDOC ## GET /api/v2/company (URL Parameter) ### Description Uses an API key as a URL parameter to authenticate a GET request to the company endpoint. This method is not recommended for security reasons. ### Method GET ### Endpoint `https://dialpad.com/api/v2/company?apikey=` ### Parameters #### Query Parameters - **apikey** (string) - Required - Your authentication token. ### Request Example ```http https://dialpad.com/api/v2/company?apikey= ``` ### Response #### Success Response (200) - **(structure varies)** - The response will contain company details. #### Response Example ```json { "example": "response body" } ``` ``` -------------------------------- ### Authenticate API Requests with Bearer Token (cURL) Source: https://developers.dialpad.com/docs/authentication-basics Demonstrates how to make authenticated GET requests to the Dialpad API using a bearer token in the Authorization header. This method is recommended for security. It includes examples for both sandbox and production environments. ```curl --SANDBOX-- curl --request GET \ --url 'https://sandbox.dialpad.com/api/v2/company/' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $accessToken' --PRODUCTION-- curl --request GET \ --url 'https://dialpad.com/api/v2/company/' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $accessToken' ``` -------------------------------- ### Invoke Dialpad App with Launch URL Source: https://developers.dialpad.com/docs/app-launch-urls This example demonstrates how to construct a Dialpad launch URL to initiate a call. It includes various optional parameters to control app behavior such as launching in minimode, confirming the phone number, specifying the 'from' number, and suppressing CRM logging or dispositions. The `customData` parameter allows passing arbitrary data back to the application. ```http dialpad://+15555555555?launchMinimode=1&confirmPhone=1&fromNumber=+15554444444&crmLogging=0&showDispositions=1&customData=this%20is%20a%20test ``` -------------------------------- ### Agent Status Event Payload Example (JSON) Source: https://developers.dialpad.com/docs/agent-status-events This JSON object represents a sample payload for an Agent Status Event. It includes details about the agent's on-duty status, call center assignments, and timestamps. This payload is sent to a user-provided webhook when an agent's status changes. ```json { "call_center_ids": [ "5883344555555555", "6214545667777777" ], "target": { "phone": "+123456789", "type": "user", "email": "test@testdomain.com", "name": "nice agent", "id": 5728255400000000 }, "on_duty_status": "unavailable", "powerdialer_session": null, "on_duty_status_reason": "snack break for 10", "powerdialer_mode": false, "date": 1620328863056, "availability_status": "unavailable", "event_timestamp":16203288633333 } ``` -------------------------------- ### Create Custom Holiday - JSON Source: https://developers.dialpad.com/docs/change-log-action-types This JSON object defines the parameters for creating a custom holiday. It includes the holiday's name, recurrence type, start date, and the target office group key. ```json {"name": "xx", "recur_type": "no_repeat", "start_on": "2023-03-03", "target_key": "OfficeGroup:00"} ``` -------------------------------- ### Inbound Call Transcription Data in JSON Source: https://developers.dialpad.com/docs/call-events This JSON example represents an inbound call that has reached the 'transcription' state. It includes details about the call, such as the call ID, direction, timestamps, and a field for transcription text, which might be empty if no transcription is available. ```json { "master_call_id": null, "date_ended": 1582853883616, "internal_number": "+16010123456", "duration": null, "total_duration": null, "entry_point_target": {}, "proxy_target": {}, "call_dispositions": null, "entry_point_call_id": null, "operator_call_id": null, "call_id": 6580619776884736, "state": "transcription", "date_started": 1582853854278, "transcription_text": "", "direction": "inbound", "date_connected": null, "voicemail_link": "https://dialpadbeta.com/v/6580619776884736", "is_transferred": false, "was_recorded": false, "date_rang": 1582853854874, "target": { "phone": "+16010123456", "type": "user", "id": 5908860123456789, "name": "sample", "email": "test@dialpad.com", "office_id": 4632479632575683 }, "contact": { "phone": "+16043111111", "type": "google", "id": "http://www.google.com/m8/feeds/contacts/test@dialpad.com/base/21042cfc8b367347", "name": "Test for a Long Name", "email": "" }, "group_id": null, "external_number": "+16043111111" } ``` -------------------------------- ### Timeout Action Payload Example - JSON Source: https://developers.dialpad.com/docs/call-routing-via-apis This JSON payload is sent to the routing_url when a 'custom' timeout_action is used. It includes call details and custom headers for reattempt tracking. ```json { "date_started": , "call_id": , "external_number": "", "internal_number": "", "contact_id": , "contact_type": , "": "" } ``` -------------------------------- ### Handle Call Ringing Notification (JavaScript) Source: https://developers.dialpad.com/docs/dialpad-mini-dialer This JavaScript code snippet demonstrates how to send a `call_ringing` message to Dialpad's CTI. This is used to open the CTI window when an inbound call starts or finishes ringing. The payload includes call state, ID, contact, and target details. ```javascript window.parent.postMessage({ 'api': 'opencti_dialpad', 'version': '1.0', 'method': 'call_ringing', 'payload': { 'state': 'on', 'id': 5747322335264768, 'contact': { 'id': 'http://www.google.com/m8/feeds/contacts/test@dialpad.com/base/21042cfc8b367347', 'phone': '+16043111111', 'type': 'Google', 'name': 'test contact', 'email': 'contact@foobar.com' }, 'target': { 'id': 5908860123456789, 'phone': '+16010123456"', 'type': 'User', 'name': 'exampe user', 'email': 'test@dialpad.com' }, 'internal_number': '+16010123456', 'external_number': '+16043111111' } }, '*'); ``` -------------------------------- ### POST /stats Source: https://developers.dialpad.com/docs/stats-api-dialpad-analytics Initiates the processing of a statistical report. A unique ID is returned upon successful processing, which can be used to retrieve the report via the GET endpoint. ```APIDOC ## POST /stats ### Description Initiates the processing of a statistical report. A unique ID is returned upon successful processing, which can be used to retrieve the report via the GET endpoint. ### Method POST ### Endpoint /stats ### Parameters #### Query Parameters - **export_type** (string) - Required - Specifies the type of export: 'stats' or 'records'. - **stat_type** (string) - Optional - Defines the specific statistical data to retrieve (e.g., 'calls', 'on_duty'). Applicable when export_type is 'stats'. - **target_type** (string) - Optional - The type of target for the report (e.g., 'office', 'call_center', 'department', 'agent'). - **target_id** (string) - Optional - The ID of the target for the report. - **office_id** (string) - Optional - The ID of the office to retrieve data for. If target_type and target_id are not provided, this can be used to aggregate data across an office. Target will always override office_id. - **is_today** (boolean) - Optional - If true, queries 'real time' tables. Overrides days_ago. - **days_ago** (integer) - Optional - Number of days in the past to query historical data. Minimum value is 0. If is_today is true, this parameter is ignored. - **days_ago_start** (integer) - Optional - Start day for historical data query. If is_today is true, this parameter is ignored. - **days_ago_end** (integer) - Optional - End day for historical data query. If is_today is true, this parameter is ignored. - **timezone** (string) - Required - A tz database name (e.g., 'America/New_York'). ### Request Example ```json { "export_type": "stats", "stat_type": "calls", "office_id": "12345", "is_today": false, "days_ago": 7, "timezone": "America/Los_Angeles" } ``` ### Response #### Success Response (200) - **id** (string) - A unique identifier for the generated report. #### Response Example ```json { "id": "report_abc123xyz789" } ``` ``` -------------------------------- ### Assigning Locale for Text-to-Speech Source: https://developers.dialpad.com/docs/call-routing-via-apis This example shows how to specify a 'locale' for text-to-speech synthesis. The locale ensures the message is spoken with a regional accent but does not translate the content. The 'message' itself should be pre-translated. ```json { "message": "Bonjour le monde", "locale": "fr-ca" } ``` -------------------------------- ### Call Ringing Notification Source: https://developers.dialpad.com/docs/dialpad-mini-dialer This API method is called by Dialpad to notify your application when an inbound call starts or finishes ringing. It is used to open the CTI window for the user to answer the call. ```APIDOC ## POST /call_ringing ### Description Notifies your application when an inbound call starts or finishes ringing. Use this message to open the CTI window for the user to answer the call. ### Method POST (via `window.parent.postMessage`) ### Endpoint Not applicable (invoked via `postMessage`) ### Parameters #### Request Body (Payload) - **state** (string) - Required - Set to `on` when the call starts ringing and to `off` when the ringing ends. Two messages are sent per call. - **id** (int) - Required - Call ID - a unique number ID automatically assigned to each call. - **contact** (object) - Required - The contact involved in the call. Contains: - **phone** (string) - Phone number of the contact. - **type** (string) - Type of the contact (e.g., User, Local, Nylas, Google, Microsoft). - **id** (string) - Unique contact ID. - **email** (string) - Associated email of the contact. - **name** (string) - Name of the contact. - **target** (object) - Required - The target that the Dialpad user dials or receives a call from. Contains: - **phone** (string) - Phone number of the target. - **type** (string) - Type of the target (e.g., User, Office, Department, Staff, Room, Call Center). - **id** (int) - Unique target ID. - **email** (string) - Associated email of the target. - **name** (string) - Name of the target. - **internal_number** (string) - Required - The phone number of the target (E.164 format). - **external_number** (string) - Required - The phone number of the contact (E.164 format). ### Request Example ```javascript window.parent.postMessage({ 'api': 'opencti_dialpad', 'version': '1.0', 'method': 'call_ringing', 'payload': { 'state': 'on', 'id': 5747322335264768, 'contact': { 'id': 'http://www.google.com/m8/feeds/contacts/test@dialpad.com/base/21042cfc8b367347', 'phone': '+16043111111', 'type': 'Google', 'name': 'test contact', 'email': 'contact@foobar.com' }, 'target': { 'id': 5908860123456789, 'phone': '+16010123456"', 'type': 'User', 'name': 'exampe user', 'email': 'test@dialpad.com' }, 'internal_number': '+16010123456', 'external_number': '+16043111111' } }, '*'); ``` ### Response No direct response is expected as this is an event notification. The action taken is to open the CTI window. ``` -------------------------------- ### GET /stats/{id} Source: https://developers.dialpad.com/docs/stats-api-dialpad-analytics Retrieves the processed statistical report using the ID obtained from the POST request. The report is returned as a CSV file. ```APIDOC ## GET /stats/{id} ### Description Retrieves the processed statistical report using the ID obtained from the POST request. The report is returned as a CSV file. ### Method GET ### Endpoint /stats/{id} ### Parameters #### Path Parameters - **id** (string) - Required - The unique identifier of the report to retrieve. ### Request Example ```json { "example": "GET /stats/report_abc123xyz789" } ``` ### Response #### Success Response (200) - **CSV Data** - The content of the statistical report in CSV format. #### Response Example ```csv Call ID,Agent,Status,Duration 1,Agent A,Answered,60 2,Agent B,Missed,0 ``` ``` -------------------------------- ### Reset Call Router Errors and Re-enable - PATCH Method Source: https://developers.dialpad.com/docs/call-routing-via-apis This example shows how to re-enable a call router and simultaneously reset its internal error count. This is beneficial for intermittent issues where the underlying problem might persist but you want to allow the router to function while addressing the root cause. ```json { "reset_error_count": true, "enabled": true } ``` -------------------------------- ### Update Custom Holiday - JSON Payload Source: https://developers.dialpad.com/docs/change-log-action-types Represents the data structure for updating a custom holiday. It includes the holiday's name, recurrence type, and start date. This format is crucial for API interactions requiring holiday management. ```json { "name": "xx", "recur_type": "no_repeat", "start_on": "2022-03-21" } ``` -------------------------------- ### Inbound Call Ringing Payload - JSON Source: https://developers.dialpad.com/docs/call-events This JSON payload represents an inbound call that is currently ringing. It includes essential call identifiers and participant details, with timestamps indicating when the call started and was initially offered. This is useful for real-time call monitoring. ```json { "master_call_id": null, "date_ended": null, "internal_number": "+16010123456", "duration": null, "total_duration": null, "entry_point_target": {}, "proxy_target": {}, "call_dispositions": null, "entry_point_call_id": null, "operator_call_id": null, "call_id": 5747322335264768, "state": "ringing", "date_started": 1582853645285, "transcription_text": null, "direction": "inbound", "date_connected": null, "voicemail_link": null, "is_transferred": false, "was_recorded": false, "date_rang": 1582853645838, "target": { "phone": "+16010123456", "type": "user", "id": 5908860123456789, "name": "sample", "email": "test@dialpad.com", "office_id": 4632479632575683 }, "contact": { "phone": "+16043111111", "type": "google", "id": "http://www.google.com/m8/feeds/contacts/test@dialpad.com/base/21042cfc8b367347", "name": "Test for a Long Name", "email": "" }, "group_id": null, "external_number": "+16043111111" } ``` -------------------------------- ### App Launch URLs Source: https://developers.dialpad.com/docs/app-launch-urls This section details how to use the Dialpad protocol to launch the application and initiate calls with various customizable parameters. ```APIDOC ## App Launch URLs ### Description Use the Dialpad protocol to invoke the Dialpad desktop application from any third-party app or browser, with options to control app behavior before dialing. ### Method GET ### Endpoint dialpad:// ### Query Parameters - **fromNumber** (string) - Optional - Allows you to switch the user's number from their assigned numbers. This number can be any of the user's numbers, or if the user is part of the operator group in a Main Line or Department, or as an agent in a Call Center - any of the DID's from these share lines can be used. - **launchMinimode** (integer) - Optional - Set to 1 to always launch in Dialpad Everywhere. - **confirmPhone** (integer) - Optional - Set to 1 to always require the user to confirm the phone number in the Dialpad app. - **customData** (string) - Optional - Specify any data that you'd like to consume back in events. - **showDispositions** (integer) - Optional - Set to 0 to suppress call dispositions in Dialpad. - **crmLogging** (integer) - Optional - Set to 0 to suppress CRM logging from Dialpad. ### Request Example ```http dialpad://+15555555555?launchMinimode=1&confirmPhone=1&fromNumber=+15554444444&crmLogging=0&showDispositions=1&customData=this%20is%20a%20test ``` ``` -------------------------------- ### Ask Action Source: https://developers.dialpad.com/docs/call-routing-via-apis The `ask` action prompts the caller with a synthesized speech message and collects their numerical input. This input is then used for subsequent routing decisions. ```APIDOC ## POST /actions/ask ### Description This action prompts the caller with a question via text-to-speech and collects their response using the number pad. The caller's input is then included in a subsequent routing request. ### Method POST ### Endpoint /actions/ask ### Parameters #### Request Body - **message** (string or array) - Required - The message to be played to the caller via text-to-speech. - **hint_name** (string) - Required - The field name in which the caller's response will appear in the post-`ask` routing request. - **finish_on_key** (string) - Optional - The key the caller should press to signal the end of input. - **num_digits** (integer) - Optional - The number of digits the caller should enter. Defaults to 99. - **valid_digits** (string) - Optional - A string containing all valid keypad values for the caller's response. Defaults to "0123456789*#". - **retries** (integer) - Optional - The number of times the prompt should be repeated if no input is received. Defaults to 10. - **timeout** (integer) - Optional - The number of seconds to wait for caller input before repeating the prompt. Defaults to 5. - **timeout_action** (string) - Optional - The action to take if the caller does not provide input after maximum retries. Defaults to `disconnect`. - **locale** (string) - Optional - The locale code for the text-to-speech voice. Defaults to US English. ### Request Example ```json { "message": "Please enter your account number.", "hint_name": "account_number", "num_digits": 10, "finish_on_key": "#" } ``` ### Response #### Success Response (200) (The response structure for a successful `ask` action is dependent on the subsequent routing logic. Typically, it would involve the status of the action.) #### Response Example ```json { "status": "success" } ``` ``` -------------------------------- ### initiate_call Source: https://developers.dialpad.com/docs/dialpad-mini-dialer Initiates an outbound call. This method opens the dial prompt and automatically makes the call if the CTI tab is enabled. If disabled, it will enable the tab first. ```APIDOC ## initiate_call ### Description Initiates an outbound call through Dialpad. Opens the dial prompt and optionally enables the CTI tab if it's not already enabled. Supports specifying the number to call, identity type, and custom data. ### Method POST (via postMessage) ### Endpoint `https://dialpad.com` (target origin for postMessage) ### Parameters #### Request Body - **enable_current_tab** (boolean) - Optional - Indicates whether the current tab should be enabled before initiating the call. Defaults to `true`. - **phone_number** (string) - Required - Phone number in E.164 format. - **identity_type** (string) - Optional - Specifies the type of identity to initiate the call through (e.g., `Office`, `OfficeGroup`, `CallCenter`). - **identity_id** (number) - Optional, but required if `identity_type` is included - The office, department, or call centre ID. - **custom_data** (string) - Optional - Data to associate with the call. Maximum 2000 characters. - **outbound_caller_id** (string) - Optional - Used instead of `identity_type` and `identity_id` to determine the target of the call. Defaults to `identity_id` if used together. ### Request Example ```javascript .contentWindow.postMessage({ 'api': 'opencti_dialpad', 'version': '1.0', 'method': 'initiate_call', 'payload': { 'enable_current_tab': false, 'phone_number': '+15555555555', 'identity_type': 'CallCenter', 'identity_id': 1234567, 'custom_data': 'any string', 'outbound_caller_id': '+18005550970' } }, 'https://dialpad.com'); ``` ### Response No specific success response is detailed, but the action is to initiate a call. Error handling for invalid parameters or call failures should be considered. ``` -------------------------------- ### OAuth Authorization Request Source: https://developers.dialpad.com/docs/oauth Initiate the OAuth flow by redirecting the user to Dialpad's authorize endpoint. ```APIDOC ## GET /oauth2/authorize ### Description Redirect the user to this endpoint to initiate the OAuth 2.0 authorization code flow. The user will be prompted to log in to Dialpad and grant your application access. ### Method GET ### Endpoint * Sandbox: `https://sandbox.dialpad.com/oauth2/authorize` * Production: `https://dialpad.com/oauth2/authorize` ### Parameters #### Query Parameters - **response_type** (string) - Required - The literal string `code`. - **client_id** (string) - Required - Your application's client ID. - **redirect_uri** (string) - Required - The URI on your website to redirect the user back to after authorization. - **state** (string) - Optional - An unpredictable value used to prevent CSRF attacks. This value should be validated in the next step. - **scope** (string) - Optional - A space-separated list of additional scopes to request. Scopes must be approved by Dialpad. - **code_challenge** (string) - Optional - A PKCE challenge value. - **code_challenge_method** (string) - Optional - The method used for the PKCE challenge (e.g., `S256`). ### Request Example ``` https://dialpad.com/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&state=YOUR_STATE_TOKEN&scope=recordings_export%20calls:list ``` ``` -------------------------------- ### Create a Call Router - Python Source: https://developers.dialpad.com/docs/call-routing-via-apis This Python snippet demonstrates how to create a new call router using the Dialpad API. It sends a POST request to the callrouters endpoint with the necessary payload, including routing details and default target information. The API returns the created call router's details upon success. ```python import requests url = "https://dialpad.com/api/v2/callrouters" payload = '''{ "default_target_id": "123456", "default_target_type": "callcenter", "name": "Hello Router", "office_id": "223456", "routing_url": "https://yourroutingservice.com/routecall", }''' headers = { 'accept': "application/json", 'content-type': "application/json" } response = requests.request("POST", url, data=payload, headers=headers) ``` -------------------------------- ### Token Acquisition via POST Source: https://developers.dialpad.com/docs/oauth Exchange the authorization code for an API access token. ```APIDOC ## POST /oauth2/token ### Description Use the authorization `code` received in Step 2 to request an API access token and an optional refresh token from Dialpad's token endpoint. ### Method POST ### Endpoint * Sandbox: `https://sandbox.dialpad.com/oauth2/token` * Production: `https://dialpad.com/oauth2/token` ### Parameters #### Request Body - **grant_type** (string) - Required - The literal string `authorization_code`. - **code** (string) - Required - The authorization code received from the `oauth2/authorize` endpoint. - **client_id** (string) - Required - Your application's client ID. - **client_secret** (string) - Required - Your application's client secret. - **redirect_uri** (string) - Required - The same redirect URI used in the authorization request. - **code_verifier** (string) - Optional - The PKCE code verifier, if `code_challenge` was used in the authorization request. ### Request Example ```json { "grant_type": "authorization_code", "code": "AUTHORIZATION_CODE", "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "redirect_uri": "YOUR_REDIRECT_URI", "code_verifier": "YOUR_CODE_VERIFIER" } ``` ### Response #### Success Response (200 OK) - **access_token** (string) - The API access token. - **token_type** (string) - The type of token, usually `Bearer`. - **expires_in** (integer) - The lifetime in seconds of the access token. - **refresh_token** (string) - A token that can be used to obtain a new access token when the current one expires (if `offline_access` scope was granted). - **scope** (string) - The scopes granted to this token. #### Response Example ```json { "access_token": "ACCESS_TOKEN", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "REFRESH_TOKEN", "scope": "recordings_export calls:list" } ``` ``` -------------------------------- ### Call States Source: https://developers.dialpad.com/docs/call-events This section details the different states a call can be in, from initiation to completion, including voicemail and AI-related states. ```APIDOC ## Call States Overview ### Description This API provides information about the various states a call can transition through. These states are crucial for understanding the lifecycle of a call and for processing related data like voicemails and transcriptions. ### Method GET ### Endpoint /websites/developers_dialpad_com-docs/call_states ### Parameters #### Query Parameters - **state** (string) - Optional - Allows filtering by a specific call state. Example: `calling` - **include** (string) - Optional - Comma-separated list of states to include. Example: `calling,ringing,connected` ### Request Example ``` GET /websites/developers_dialpad_com-docs/call_states?state=connected ``` ### Response #### Success Response (200) - **states** (array) - A list of available call state objects. - **state** (string) - The name of the call state. - **description** (string) - A detailed description of the call state. #### Response Example ```json { "states": [ { "state": "calling", "description": "Outbound call has started." }, { "state": "ringing", "description": "Inbound call is ringing." }, { "state": "connected", "description": "Both parties in an outbound or inbound call have answered the call and can hear each other." } // ... other states ] } ``` ### Notes - The `transcription` state is for voicemail transcriptions. AI transcriptions are available via the `call_transcription` state. - AI transcriptions can be retrieved using the `GET transcripts` API or the `recap_summary` state. - The `voicemail` state may populate `voicemail_link` proactively, but it might 404 if the voicemail is cancelled early. ``` -------------------------------- ### OAuth Authorization Response Source: https://developers.dialpad.com/docs/oauth Handle the redirect back from Dialpad, which includes an authorization code and the state token. ```APIDOC ## Handling the Redirect ### Description After the user authorizes your application, Dialpad will redirect the user back to your specified `redirect_uri` with `code` and `state` query parameters. ### Parameters #### Query Parameters - **code** (string) - Temporary authorization code. Valid for 1 minute. - **state** (string) - The CSRF token sent in the authorization request. Validate this against the state you originally sent. ### Response Example Your `redirect_uri` will receive a request similar to this: ``` YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=YOUR_STATE_TOKEN ``` **Important:** If the `state` parameter does not match the one sent in the authorization request, do not proceed with the OAuth flow due to potential CSRF risks. ``` -------------------------------- ### Supported Locales for Text-to-Speech Source: https://developers.dialpad.com/docs/call-routing-via-apis A list of supported locale codes for text-to-speech synthesis and an explanation of their functionality. ```APIDOC ## Supported Locales Dialpad supports the following locales for text-to-speech synthesis. Passing an invalid locale will default to English (US). > **Note:** Locale specifies the accent, not the language. Provide translated text in the `message` field. | Locale Code | Language | | :---------- | :------------------ | | `de` | German | | `en` | English (US) | | `en-au` | English (Australia) | | `en-gb` | English (British) | | `es` | Spanish (US) | | `fr` | French | | `fr-ca` | French (Canadian) | | `it` | Italian | | `ja` | Japanese | | `nl` | Dutch | | `pt` | Portuguese (Brazil) | | `ru` | Russian | | `zh` | Chinese, Mandarin | ``` -------------------------------- ### Text-to-Speech (TTS) Best Practices Source: https://developers.dialpad.com/docs/call-routing-via-apis Guidelines for optimizing text-to-speech fields, such as the `message` field, for improved performance and playback latency. ```APIDOC ## Text-to-Speech (TTS) For optimal text-to-speech results, the `message` field should contain a single short string or an array of short strings. ### Optimization Tips: * Split messages into smaller segments. * Prioritize the first string in a list for quicker playback initiation. * Place dynamic strings after an initial static string to leverage caching. ``` -------------------------------- ### Handle User Authentication Status (JavaScript) Source: https://developers.dialpad.com/docs/dialpad-mini-dialer This JavaScript code illustrates how to send a 'user_authentication' message from the parent window to the Dialpad CTI iframe. It utilizes the `window.postMessage` API to communicate the authentication status and user ID of the logged-in user. ```javascript window.parent.postMessage({ 'api': 'opencti_dialpad', 'version': '1.0', 'method': 'user_authentication', 'payload': { 'user_authenticated': true, 'user_id': 1234567 } }, '*'); ``` -------------------------------- ### Embed Dialpad CTI in an iframe (HTML) Source: https://developers.dialpad.com/docs/dialpad-mini-dialer This HTML snippet demonstrates how to embed the Dialpad CTI into a webpage using an iframe. It specifies the source URL with a client ID placeholder and includes essential 'allow' attributes for microphone, camera, display capture, and HID access, along with sandbox attributes for security. ```html ``` -------------------------------- ### Change Log Action Types Reference Source: https://developers.dialpad.com/docs/change-log-action-types This section details the structure of change log events, including the 'action', 'note', and 'additional data' fields. It also explains how to interpret the 'note' and 'additional data' based on different action types. ```APIDOC ## Change Log Action Types Reference Change log events contain the following fields to describe the change: `action`, `note`, and `additional data`. ### Action Types The following table lists common action types and their associated `note` and `additional data` structures: | Action (string) | Note (string) | Additional Data (json) | | :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `add_team_members` | Blocked new invite because the account already invited 5 users... | `{"0": "xx\@xx"}` | | `add_vm_fax_subscriber` | Updated group | params: ["add_vm_fax_subscriber", {"email": "xx@xx", "subscriptions": {"vmSubscribed": true, "faxSubscribed": false}}] | `{ "email": "xx@xx", "name": "xx", "subscriptions": { "faxSubscribed": false, "vmSubscribed": true } }` | ### Proxying Behavior Change logs triggered while a superuser is proxying will have `PROXYING AS xxx@xxx |` prepended to the beginning of the `note`. The change will be accredited to the superuser unless a Dialpad employee conducted the change. ``` -------------------------------- ### Room Management API Source: https://developers.dialpad.com/docs/change-log-action-types Endpoints for managing conference rooms, including creation, deletion, and editing. ```APIDOC ## POST /room_added ### Description Creates a new conference room. Use this endpoint to set up new virtual meeting spaces. ### Method POST ### Endpoint /room_added ### Parameters #### Request Body - **name** (string) - Required - The name of the room to be added. ### Request Example ```json { "room_name": "xxx" } ``` ### Response #### Success Response (200) - **message** (string) - Confirmation message. #### Response Example ```json { "message": "Room added successfully." } ``` ## DELETE /room_deleted ### Description Deletes an existing conference room. Use this when a room is no longer needed. ### Method DELETE ### Endpoint /room_deleted ### Parameters #### Request Body - **room_name** (string) - Required - The name of the room to delete. ### Request Example ```json { "room_name": "xxx" } ``` ### Response #### Success Response (200) - **message** (string) - Confirmation message. #### Response Example ```json { "message": "Room deleted successfully." } ``` ## PUT /room_edited ### Description Edits an existing conference room's properties. Allows modification of room settings like name, caller ID, and international calling options. ### Method PUT ### Endpoint /room_edited ### Parameters #### Request Body - **room_name** (string) - Required - The name of the room to edit. - **caller_id** (string) - Optional - The caller ID for the room. - **caller_id_override** (string) - Optional - An override for the caller ID. - **international_calling_disabled** (boolean) - Optional - Disable international calling for the room. - **name** (string) - Optional - The new name for the room. - **no_answer_action** (string) - Optional - The action to take when there is no answer. ### Request Example ```json { "caller_id": "", "caller_id_override": "+xxx", "international_calling_disabled": false, "name": "xxx", "room_name": "xxx", "no_answer_action": "message" } ``` ### Response #### Success Response (200) - **message** (string) - Confirmation message. #### Response Example ```json { "message": "Room edited successfully." } ``` ``` -------------------------------- ### Text-to-Speech Message Formatting - Array of Strings Source: https://developers.dialpad.com/docs/call-routing-via-apis This illustrates the recommended way to format the 'message' field for text-to-speech. Providing the message as an array of short strings allows for independent processing and quicker playback initiation, especially when the first string is static and can be cached. ```json { "message": [ "This is the first string.", "This is the second string." ] } ``` -------------------------------- ### Enable VI Override - JSON Source: https://developers.dialpad.com/docs/change-log-action-types This snippet shows how to enable the VI override functionality. It involves setting a boolean value to true in a JSON object. ```json {"to": true} ``` -------------------------------- ### Sample Change Log Event Payload (JSON) Source: https://developers.dialpad.com/docs/change-log-events This JSON object represents a typical change log event payload, detailing the action, additional data, who made the change, timestamp, note, and the target of the change. ```json { "action": "operator_removed", "additional_data": { "name": "Dialpedia Ltd", "operator_name": "Mary Sue" }, "changed_by": { "name": "John Doe", "id": 000000000, "type": "User", }, "date": 1620328863056, "note": "Operator removed", "target": { "type": "Office", "id": 1111111 } } ``` -------------------------------- ### Authenticate API Requests with URL Parameter (HTTP) Source: https://developers.dialpad.com/docs/authentication-basics Illustrates how to authenticate Dialpad API requests by including the API key as a URL parameter. This method is discouraged due to security risks associated with exposing API keys in URLs and logs. ```http https://dialpad.com/api/v2/company?apikey= ``` -------------------------------- ### Route Call Action Configuration Source: https://developers.dialpad.com/docs/call-routing-via-apis Configuration for the 'route' action, used to transfer calls to a specific Dialpad target. Requires both the target's ID and its type (e.g., office, user). ```json { "action": "route", "target_id": , "target_type": "office" | "department" | "callcenter" | "user" } ``` -------------------------------- ### End Action Configuration - JSON Source: https://developers.dialpad.com/docs/call-routing-via-apis Configuration for an 'end' action, which plays a text-to-speech message before disconnecting the call. It includes the message content and an optional locale for voice selection. ```json { "action": "end", "message": "Thank you for calling.", "locale": "en-US" } ``` -------------------------------- ### Set Real-Time VI - JSON Source: https://developers.dialpad.com/docs/change-log-action-types This snippet demonstrates how to set the real-time VI (Visual Indicator) to off. It's a simple JSON payload. ```json {"to": false} ``` -------------------------------- ### enable_current_tab Source: https://developers.dialpad.com/docs/dialpad-mini-dialer This method allows the CTI tab to be enabled for making and receiving calls. Dialpad only allows one CTI tab to be enabled at a time. There is no payload for this method. ```APIDOC ## enable_current_tab ### Description Enables the current CTI tab for making and receiving calls. Only one CTI tab can be enabled at a time. ### Method POST (via postMessage) ### Endpoint `https://dialpad.com` (target origin for postMessage) ### Parameters None ### Request Example ```javascript .contentWindow.postMessage({ 'api': 'opencti_dialpad', 'version': '1.0', 'method': 'enable_current_tab' }, 'https://dialpad.com'); ``` ### Response No specific response is detailed, but the action is to enable the CTI tab. ``` -------------------------------- ### POST /callrouters Source: https://developers.dialpad.com/docs/call-routing-via-apis Creates a new call router. You can specify a name, the URL to consult for routing, an optional JWT secret, the office ID, and a default target for fallback routing. ```APIDOC ## POST /callrouters ### Description Creates a new call router. This allows you to define rules for routing incoming calls. ### Method POST ### Endpoint /callrouters ### Parameters #### Request Body - **name** (string) - Required - Specify a name for the call router - **routing_url** (string) - Required - The URL that should be consulted to route calls - **secret** (string) - Optional - A JWT secret to be used for authentication - **office_id** (string) - Required - The office to which the call router belongs - **default_target_id** (string) - Required - The fallback target ID to be used in case of client server unavailability - **default_target_type** (string) - Required - The type associated with the default_target_id (e.g., office, department, callcenter, user) - **enabled** (boolean) - Optional - Set to `true` by default. If set to `false`, the call router acts as a pass-through to the office mainline. ### Request Example ```json { "default_target_id": "123456", "default_target_type": "callcenter", "name": "Hello Router", "office_id": "223456", "routing_url": "https://yourroutingservice.com/routecall" } ``` ### Response #### Success Response (200) - **id** (string) - The generated unique identifier for the call router. - **name** (string) - The name of the call router. - **routing_url** (string) - The URL configured for call routing. - **office_id** (string) - The ID of the office associated with the call router. - **default_target_id** (string) - The fallback target ID. - **default_target_type** (string) - The type of the fallback target. - **enabled** (boolean) - Indicates if the call router is enabled. - **phone_numbers** (array) - A list of phone numbers assigned to this call router. - **signature** (object) - Information about the signature used for the router: - **type** (string) - The type of signature (e.g., "jwt"). - **algo** (string) - The algorithm used for the signature (e.g., "HS256"). - **secret** (string) - The secret key used for the signature. #### Response Example ```json { "id": "generated id", "name": "name", "routing_url": "routing_url", "office_id": "office_id", "default_target_id": "12341234", "default_target_type": "callcenter", "enabled": true, "phone_numbers": ["e164 number", ...], "signature": { "type": "jwt", "algo": "HS256", "secret": "secret" } } ``` ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.