Dialpad Call Logging Endpoint

 

NOTICE: We've relocated our API documentation to the developers website. In this Help Center article, some information below is incorrect; use the developers website to understand Dialpad's APIs as it is constantly updated to remain accurate.

--------------------------------------------------

This API provides a call logging ‘endpoint’ to organizations on the Pro or Enterprise plans. With access to this endpoint, customers can designate a specific URL that they want to call logging events to be sent to as webhooks.

To set up a call logging endpoint, navigate hereEvent Subscriptions and Authentication Basics pages might serve as useful.

We also recommend reviewing this Help Center article on creating and accessing an API key; you'll need to create a company-issued API key, not an Office-issued one or any other type. You can also get answers to API-related questions using our developer discussion board.

Objects You Get from Dialpad

Field

Description

Notes

internal_number

The phone number internal to your organization

For inbound calls, this is the destination number. For outbound calls, this is the caller’s number.

external_number

The phone number external to your organization

For inbound calls, this is the caller’s number. For outbound calls, this is the destination number.

target

This is the 'target' that the Dialpad user dials or receives a call from. It will contain the following pieces of info:


Phone: E.164 phone number

Type: User/Office/Department/Staff/Room/Call Center

ID: Unique Target ID

Email: Associated email

Name: Target name

May appear blank if unanswered.


The target corresponds to the internal_number. It’s the Dialpad user or Department or Call Center, regardless of whether the call is inbound or outbound.

proxy_target

Caller ID used by the Dialpad user for outbound calls.  It will contain the following pieces of info:

 

Phone: E.164 phone number

Type: Office/Department/Staff/Room/Call Center

Id: Unique proxy ID

Email: Associated email

If a value appears, the call was placed with an outbound ID other than the user's direct line.

entry_point_target

Where a call initially dialed for inbound calls to Dialpad.  It will contain the following pieces of info:


Phone: E.164 phone number

Type: User/Office/Department/Staff/Room/Call Center

Id:Unique entry point ID

Email: Associated email

Inbound calls only.

This is populated when an inbound call is fanned out to a Dept/Call Queue.

call_id

A unique number ID automatically assigned to each call

 

entry_point_call_id

Call ID of the associated entry point call.

This is defined for operator calls (departments, call queues). It can be used to associate an operator call with its entry point call.

group_id

Unique ID of the department, mainline, or call queue associated with the call.

This matches the entry_point_target for a group call.


May appear blank if the call is not a group call.

direction

Call direction. Indicates whether a call was made (outbound) or received (inbound).

 

contact

This is the contact involved in the call. It will contain the following pieces of info:


Phone: E.164 phone number

Type: User/Local/Nylas/Google/Microsoft

ID: Unique contact ID

Email: Associated email

Name: Contact name

The contact corresponds to the external_number, regardless of whether the call is inbound or outbound.

date_started

Timestamp when the call began in the Dialpad system before being connected

 

date_rang

Timestamp when Dialpad first detects an inbound call to a mainline, department, or person.

May appear blank if:


  • The caller hung up before we could detect ringing.
  • The user has IVR settings that put callers directly to VM.
  • The call is an outbound call.

date_connected

Timestamp when Dialpad connected the call

May appear blank if:


  • Dialpad did not detect a date_rang value.
  • Agent did not answer (Call Queues).

date_ended

Timestamp when the call was hung up.

 

duration

Duration of the call in milliseconds

May be blank if:


  • The call is not yet completed. (Before the ‘hangup’ state)
  • The call was never connected.

state

preanswer

calling

ringing

connected

merged

hold

queued

voicemail

eavesdrop

hangup

blocked

admin

parked

 

was_recorded

Boolean indicating whether or not the call was recorded

 

voicemail_link

URL to the voicemail recording

May appear blank if there was no voicemail left.

 

The Event Loop

Workflows built using the Dialpad call logging endpoint will follow the same abstract event-driven sequence:

  1. A user creates a circumstance that triggers an event subscription to your application
  2. Your server receives a JSON object, encoded with jwt  with the secret you gave us
  3. Your server acknowledges receipt of the event
  4. Your business logic decides what to do about that event
  5. Your server carries out that decision

Dialpad Call Logging Endpoint | Request URLs

Request URLs operate like this:

  • They all receive an HTTP POST containing data in response to activity.
  • In the call logging endpoint, your Request URL is the target location where all the events your application is subscribed to will be delivered
  • Since your application will have only one Request URL, you won’t need to do any additional dispatch or routing server-side after receiving event data.
  • Your Request URL will receive JSON-based payloads containing wrapped event types (described above).

Events Dispatched as JSON

When an event in your subscription occurs in an authorized user's account, we'll send an HTTP POST request to your Request URL. Once you receive the event, you'll want to use a 200-series HTTP status code to indicate success. If you don’t respond with 200, we will retry once.

Here an example of a decoded JSON response from the call logging endpoint:

{  
  "internal_number":"14155551001",
  "target":{  
     "phone":"+14155551001",
     "type":"user",
     "id":2,
     "email":"bot@fuzz-ball.com"
  },
  "date_ended":1494624100265,
  "proxy_target":{  

  },
  "date_connected":1494624100265,
  "direction":"inbound",
  "call_id":7,
  "state":"hangup",
  "external_number":"14155556666",
  "was_recorded":false,
  "entry_point_target":{  

  },
  "date_rang":1494624100265,
  "date_started":1494624097927
}

Frequently Asked Questions (FAQs)

Are any events/errors passed to the customer when attempting to use the call logging endpoint?

No, the only indication that something is not working is if the customer does not receive any information when a call happens. 

Can we support multiple endpoints per company?

No, the only support setting up one endpoint per company at this time.

Are there any rate limits per day?

No, there are no rate limits at this time.

Was this article helpful?

/