A Ruby client for the Dialpad API that provides easy access to webhooks, subscriptions, contacts, and calls with full CRUD operations and comprehensive validation. Built with a clean object-oriented architecture using DialpadObject as the base class for all API resources.
Add this line to your application's Gemfile:
gem 'dialpad'And then execute:
$ bundle install
Or install it yourself as:
$ gem install dialpad
The gem can be configured in two ways:
Set the following environment variables:
export DIALPAD_API_BASE_URL="https://dialpad.com/api/v2"
export DIALPAD_API_TOKEN="your_api_token_here"require 'dialpad'
Dialpad.configure do |config|
config.base_url = "https://dialpad.com/api/v2"
config.token = "your_api_token_here"
endrequire 'dialpad'
client = Dialpad::Client.new(
base_url: "https://dialpad.com/api/v2",
token: "your_api_token_here"
)# List all webhooks
webhooks = Dialpad::Webhook.list
# Retrieve a specific webhook
webhook = Dialpad::Webhook.retrieve(webhook_id)
# Create a new webhook (requires hook_url)
new_webhook = Dialpad::Webhook.create({
hook_url: "https://your-app.com/webhooks/dialpad"
})
# Update a webhook
updated_webhook = Dialpad::Webhook.update(webhook_id, {
hook_url: "https://your-app.com/webhooks/dialpad-updated"
})
# Delete a webhook
Dialpad::Webhook.destroy(webhook_id)
# Access webhook attributes
puts webhook.id # => 1
puts webhook.hook_url # => "https://example.com/webhook"
puts webhook.signature # => "webhook_signature"The gem provides separate classes for different event types:
# List call event subscriptions
subscriptions = Dialpad::Subscriptions::CallEvent.list
# Retrieve a specific call event subscription
subscription = Dialpad::Subscriptions::CallEvent.retrieve(subscription_id)
# Create a new call event subscription (requires webhook_id)
new_subscription = Dialpad::Subscriptions::CallEvent.create({
webhook_id: webhook_id,
call_states: ["completed", "started"]
})
# Update a call event subscription
updated_subscription = Dialpad::Subscriptions::CallEvent.update(subscription_id, {
call_states: ["completed", "started", "ended"]
})
# Delete a call event subscription
Dialpad::Subscriptions::CallEvent.destroy(subscription_id)
# Access subscription attributes
puts subscription.id # => 1
puts subscription.call_states # => ["completed", "started"]
puts subscription.enabled # => true
puts subscription.group_calls_only # => false# List contact event subscriptions
subscriptions = Dialpad::Subscriptions::ContactEvent.list
# Retrieve a specific contact event subscription
subscription = Dialpad::Subscriptions::ContactEvent.retrieve(subscription_id)
# Create a new contact event subscription (requires webhook_id)
new_subscription = Dialpad::Subscriptions::ContactEvent.create({
webhook_id: webhook_id,
contact_type: "user"
})
# Update a contact event subscription
updated_subscription = Dialpad::Subscriptions::ContactEvent.update(subscription_id, {
contact_type: "company"
})
# Delete a contact event subscription
Dialpad::Subscriptions::ContactEvent.destroy(subscription_id)
# Access subscription attributes
puts subscription.id # => 1
puts subscription.contact_type # => "user"
puts subscription.enabled # => true
puts subscription.webhook # => webhook object
puts subscription.websocket # => websocket object# List all contacts
contacts = Dialpad::Contact.list
# Retrieve a specific contact
contact = Dialpad::Contact.retrieve(contact_id)
# Create a new contact (requires first_name and last_name)
new_contact = Dialpad::Contact.create({
first_name: "John",
last_name: "Doe",
emails: ["john.doe@example.com"],
phones: ["+1234567890"]
})
# Create or update contact with UID
contact = Dialpad::Contact.create_or_update({
first_name: "John",
last_name: "Doe",
uid: "unique_identifier"
})
# Update a contact
updated_contact = Dialpad::Contact.update(contact_id, {
first_name: "Jane",
emails: ["jane.doe@example.com"]
})
# Delete a contact
Dialpad::Contact.destroy(contact_id)
# Access contact attributes
puts contact.id # => 1
puts contact.first_name # => "John"
puts contact.last_name # => "Doe"
puts contact.display_name # => "John Doe"
puts contact.company_name # => "Acme Corp"
puts contact.job_title # => "Software Engineer"
puts contact.emails # => ["john.doe@example.com"]
puts contact.phones # => ["+1234567890"]
puts contact.primary_email # => "john.doe@example.com"
puts contact.primary_phone # => "+1234567890"
puts contact.extension # => "1234"
puts contact.owner_id # => 123
puts contact.type # => "user"
puts contact.trunk_group # => "main"
puts contact.urls # => ["https://example.com"]# List all calls
calls = Dialpad::Call.list
# Retrieve a specific call
call = Dialpad::Call.retrieve(call_id)
# Access call attributes
puts call.call_id # => "call_123"
puts call.direction # => "inbound"
puts call.state # => "completed"
puts call.date_started # => 1704110400
puts call.date_ended # => 1704110520
puts call.date_connected # => 1704110410
puts call.date_first_rang # => 1704110405
puts call.date_queued # => 1704110400
puts call.date_rang # => 1704110405
puts call.duration # => 120
puts call.total_duration # => 120
puts call.talk_time # => 100
puts call.hold_time # => 20
puts call.external_number # => "+1234567890"
puts call.internal_number # => "+0987654321"
puts call.target # => "target_info"
puts call.entry_point_target # => "entry_point"
puts call.entry_point_call_id # => "entry_call_123"
puts call.operator_call_id # => "operator_123"
puts call.master_call_id # => "master_123"
puts call.proxy_target # => "proxy_info"
puts call.group_id # => 456
puts call.is_transferred # => false
puts call.was_recorded # => true
puts call.callback_requested # => false
puts call.csat_score # => 5
puts call.mos_score # => 4.2
puts call.target_availability_status # => "available"
puts call.transcription_text # => "Hello, how can I help you?"
puts call.voicemail_link # => "https://voicemail.url"
puts call.voicemail_recording_id # => "vm_123"
puts call.call_recording_ids # => ["rec_123", "rec_456"]
puts call.labels # => ["important", "follow-up"]
puts call.integrations # => integration objects
puts call.recording_details # => recording details
puts call.routing_breadcrumbs # => routing info
puts call.contact # => contact object
puts call.event_timestamp # => 1704110400All API responses are returned as DialpadObject instances with dynamic attribute access:
webhook = Dialpad::Webhook.retrieve(1)
puts webhook.id # => 1
puts webhook.hook_url # => "https://example.com/webhook"
puts webhook.signature # => "webhook_signature"
# All objects support method_missing for dynamic attribute access
contact = Dialpad::Contact.retrieve(1)
puts contact.first_name # => "John"
puts contact.last_name # => "Doe"
puts contact.emails # => ["john@example.com"]Each object type has predefined attributes available through the ATTRIBUTES constant:
- Webhook:
id,hook_url,signature - Contact:
id,first_name,last_name,display_name,company_name,job_title,emails,phones,primary_email,primary_phone,extension,owner_id,type,trunk_group,urls - Call:
call_id,direction,state,date_started,date_ended,duration,external_number,internal_number, and many more - CallEvent Subscription:
id,call_states,enabled,group_calls_only,webhook - ContactEvent Subscription:
id,contact_type,enabled,webhook,websocket
The gem includes comprehensive validation for required attributes using the Validations module:
- Webhooks:
hook_urlfor create operations - Call Event Subscriptions:
webhook_idfor create operations - Contact Event Subscriptions:
webhook_idfor create operations - Contacts:
first_nameandlast_namefor create operations,uidfor create_or_update operations - All Resources:
idfor retrieve, update, destroy operations
# This will raise Dialpad::Webhook::RequiredAttributeError
Dialpad::Webhook.create({})
# This will raise Dialpad::Contact::RequiredAttributeError
Dialpad::Contact.create({ email: "test@example.com" })
# This will raise Dialpad::Call::RequiredAttributeError
Dialpad::Call.retrieve(nil)
# This will raise Dialpad::Subscriptions::CallEvent::RequiredAttributeError
Dialpad::Subscriptions::CallEvent.create({})
# This will raise Dialpad::Subscriptions::ContactEvent::RequiredAttributeError
Dialpad::Subscriptions::ContactEvent.create({})The gem raises appropriate exceptions for different error conditions:
begin
webhook = Dialpad::Webhook.retrieve(999)
rescue Dialpad::APIError => e
puts "API Error: #{e.message}"
rescue Dialpad::ConfigurationError => e
puts "Configuration Error: #{e.message}"
rescue Dialpad::Webhook::RequiredAttributeError => e
puts "Validation Error: #{e.message}"
endDialpad::Error- Base error classDialpad::APIError- HTTP/API related errors (4xx, 5xx status codes)Dialpad::ConfigurationError- Missing configuration (base_url or token)Dialpad::DialpadObject::RequiredAttributeError- Base validation error classDialpad::Webhook::RequiredAttributeError- Webhook validation errorsDialpad::Subscriptions::CallEvent::RequiredAttributeError- Call event validation errorsDialpad::Subscriptions::ContactEvent::RequiredAttributeError- Contact event validation errorsDialpad::Contact::RequiredAttributeError- Contact validation errorsDialpad::Call::RequiredAttributeError- Call validation errors
The gem uses a Client class that handles all HTTP communication with the Dialpad API:
GET- Retrieve resources (list, retrieve)POST- Create new resourcesPUT- Update resources (full update)PATCH- Partial updates (used by Contact.update)DELETE- Remove resources
You can also use the client directly for custom API calls:
# Direct client usage
client = Dialpad.client
# GET request
response = client.get('custom/endpoint', { param: 'value' })
# POST request
response = client.post('custom/endpoint', { data: 'value' })
# PUT request
response = client.put('custom/endpoint', { data: 'value' })
# PATCH request
response = client.patch('custom/endpoint', { data: 'value' })
# DELETE request
response = client.delete('custom/endpoint')- 2xx responses: Return parsed JSON as Hash objects
- 4xx/5xx responses: Raise
Dialpad::APIErrorwith status code and error message
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/dialpad-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the MIT License.