Ruby client for DIDWW API v3.
The DIDWW API provides a simple yet powerful interface that allows you to fully integrate your own applications with DIDWW services. An extensive set of actions may be performed using this API, such as ordering and configuring phone numbers, setting capacity, creating SIP trunks and retrieving CDRs and other operational data.
The DIDWW API v3 is a fully compliant implementation of the JSON API specification.
This SDK uses json_api_client for JSON:API serialization and deserialization.
Read more https://doc.didww.com/api
This SDK targets DIDWW API version 2026-11-19 (DIDWW::Client::DEFAULT_API_VERSION). The version is not sent as a header: it is requested in the api_version of every access token the SDK mints (see Authentication).
| Gem Version | Branch | DIDWW API Version |
|---|---|---|
| 7.x | master |
2026-11-19 |
| 6.x | release-6 |
2026-04-16 |
| 5.x | 2022-05-10 |
2022-05-10 |
| 3.x | release-3 |
2021-12-15 |
| 2.x | release-2 |
2021-04-19 |
| 1.x | release-1 |
2017-09-18 |
Add this line to your application's Gemfile:
gem 'didww-v3'And then execute:
$ bundle
Or install it yourself as:
$ gem install didww-v3
- Ruby 3.3+
require 'didww'
DIDWW::Client.configure do |config|
config.api_key = 'YOUR_API_KEY'
config.api_mode = :sandbox
end
# Check balance
balance = DIDWW::Client.balance
puts "Balance: #{balance.total_balance}"
# List DID groups with stock keeping units
did_groups = DIDWW::Client.did_groups
.includes(:stock_keeping_units)
.where(area_name: 'Acapulco')
.all
puts "DID groups: #{did_groups.count}"For details on obtaining your API key please visit https://doc.didww.com/api3/configuration.html
- Scripts for every resource:
examples/ - Rails integration sample: https://github.com/didww/didww-v3-rails-sample
require 'didww'
# Sandbox
DIDWW::Client.configure do |config|
config.api_key = 'YOUR_API_KEY'
config.api_mode = :sandbox
end
# Production
DIDWW::Client.configure do |config|
config.api_key = 'YOUR_API_KEY'
config.api_mode = :production
end| Option | Default | Description |
|---|---|---|
api_key |
— | Your DIDWW API key. It is sent only to the token service. |
api_mode |
:sandbox |
:sandbox or :production. |
api_version |
DIDWW::Client::DEFAULT_API_VERSION |
API version requested in every token. See API Version. |
scope |
nil |
nil, :read or :full. nil leaves the scope to the token service, which grants full. See Scope. |
token_store |
DIDWW::Auth::MemoryStore.new |
Cache for access tokens. See Token cache. |
logger |
Logger.new($stderr, level: :warn) |
Receives the token warnings. Set it to Rails.logger, or to nil to silence them. |
customize_connection { |conn| } |
— | Customizes the JSON:API connection. |
customize_faraday { |faraday| } |
— | Customizes the other connections: token service, prices, export download and file upload. |
| Environment | API | Token service | Voice IN prices | Voice OUT prices | SMS prices |
|---|---|---|---|---|---|
:production |
https://api.didww.com/v3/ |
https://auth.didww.com |
https://api-vin.didww.com/v3/ |
https://api-vout.didww.com/v3/ |
https://api-sms.didww.com/v3/ |
:sandbox |
https://sandbox-api.didww.com/v3/ |
https://auth-sandbox.didww.com |
https://api-vin-sandbox.didww.com/v3/ |
https://api-vout-sandbox.didww.com/v3/ |
https://api-sms-sandbox.didww.com/v3/ |
Each base URL can be overridden with an environment variable, for example to send the traffic through a proxy. Tokens are still requested for the production audiences listed in Authentication.
| Variable | Overrides |
|---|---|
DIDWW_API_URL |
API base URL. End it with /. |
DIDWW_AUTH_URL |
Token service base URL |
DIDWW_API_VIN_URL |
Voice IN prices base URL |
DIDWW_API_VOUT_URL |
Voice OUT prices base URL |
DIDWW_API_SMS_URL |
SMS prices base URL |
Use customize_connection to customize the underlying JSON:API connection, for example to configure a proxy or add custom middleware:
# Using a proxy
DIDWW::Client.configure do |config|
config.api_key = 'YOUR_API_KEY'
config.api_mode = :production
config.customize_connection do |conn|
# conn is a JsonApiClient::Connection instance
conn.faraday.proxy = 'http://proxy.example.com:8080'
end
end# Adding custom middleware and timeouts
DIDWW::Client.configure do |config|
config.api_key = 'YOUR_API_KEY'
config.api_mode = :production
config.customize_connection do |conn|
# conn is a JsonApiClient::Connection instance
conn.use MyCustomMiddleware
conn.faraday.options.timeout = 30
conn.faraday.options.open_timeout = 10
end
endThe token service, prices, export download and file upload use their own Faraday connections. customize_faraday is called with each of them after it is built, so a proxy has to be set in both blocks:
DIDWW::Client.configure do |config|
config.api_key = 'YOUR_API_KEY'
config.api_mode = :production
config.customize_connection { |conn| conn.faraday.proxy = 'http://proxy.example.com:8080' }
config.customize_faraday do |faraday|
# faraday is a Faraday::Connection instance
faraday.proxy = 'http://proxy.example.com:8080'
end
endThese connections open with a 10 s timeout and read with 60 s, except the token service, which reads with 10 s. A timeout set in customize_faraday applies to all of them, the token service included.
Every token is requested for DIDWW::Client.api_version, which defaults to DIDWW::Client::DEFAULT_API_VERSION. with_api_version overrides it for a block. The override applies only to the current thread, so concurrent requests on other threads keep their own version:
DIDWW::Client.with_api_version('2099-01-01') do
DIDWW::Client.countries.all
endBoth api_version= and with_api_version raise ArgumentError for a value that is not a YYYY-MM-DD date, and for a version earlier than DIDWW::Client::DEFAULT_API_VERSION. The resources of earlier API versions are not in this gem: use didww-v3 6.x from the release-6 branch for API 2026-04-16.
Every request carries Authorization: Bearer <token>. The SDK mints the token itself with POST /token on the token service, sending your api_key in the Api-Key header. The API key is sent nowhere else. No code change is needed: api_key and api_mode work as before.
-
Audience. Each token names the one service it is used for, as the production hostname of that service, in the sandbox too:
Calls Token audience JSON:API resources, export download, encrypted file upload api.didww.comVoice IN prices api-vin.didww.comVoice OUT prices api-vout.didww.comSMS OUT (A2P, P2P, OTP) and SMS IN prices api-sms.didww.comA token is minted on the first call to a service and reused until it expires.
GET /public_keysis sent without a token. -
Expiry and 401. The SDK asks for the longest lifetime the token service grants, one hour (
expires_in: 3600); a cached token expires with theexpires_ingranted, with no local expiry margin. When a request is answered 401, the SDK drops that token, mints a new one and sends the request again, once. A second 401 drops the new token too and is raised (see Error Handling). A 403 is never retried. -
Token service errors. A 429 raises
DIDWW::Auth::RateLimitedwithretry_after; until that time has passed, plus a small random delay so that clients do not retry in step, every further mint in the process raises the same error without a request. A 5xx answer, a connection failure or a timeout is retried with exponential backoff and jitter (0.5 s base, 8 s cap, 4 attempts in all). A 400, a 401 or a TLS failure is raised at once. See Error Handling for the error classes.
DIDWW::Client.scope = :read # GET and HEAD only
DIDWW::Client.scope = :full
DIDWW::Client.scope = nil # the default: scope is not sent, the token service grants fullA read token is enough for the price lookups and price files. A write with a read token is answered 403: resources raise JsonApiClient::Errors::AccessDenied, and EncryptedFile.upload raises DIDWW::Resource::EncryptedFile::UploadError.
The SDK compares each token it receives with what it asked for:
- a different
scope(for examplefullgranted for areadrequest) or a differentapi_versionis logged as a warning throughDIDWW::Client.logger, and the token is used; - a token whose
auddoes not include the requested audience raisesDIDWW::Auth::InvalidGrant.
Tokens are cached in DIDWW::Client.token_store, keyed by environment, API key (as a SHA-256 hash), audience, API version and scope. Each entry expires with the token's expires_in.
The default DIDWW::Auth::MemoryStore lives in the Ruby process, so a Puma or Sidekiq worker reuses a token across requests. Threads of one process that need the same token wait for a single mint. To share tokens between processes, use any store that responds to read(key), write(key, value, expires_in:) and delete(key), such as an ActiveSupport::Cache::Store:
DIDWW::Client.token_store = Rails.cacheA store that keeps nothing, such as Rails' :null_store, makes the SDK mint a token on every call. A shared store holds live bearer tokens, so protect it like a credential. Processes that share a store can each mint once when a token is missing.
Token warnings go to DIDWW::Client.logger. Each mint is also published as the ActiveSupport::Notifications event mint_token.didww, with the payload keys aud, scope_requested, scope_granted, api_version and expires_in. A mint that fails publishes the event too, with ActiveSupport's exception and exception_object keys and only aud and scope_requested set. A token taken from the cache, a mint refused inside a Retry-After window and an error shared with threads that waited for the same mint publish nothing. Neither the logs nor the event include the token or the API key.
ActiveSupport::Notifications.subscribe('mint_token.didww') do |event|
aud = event.payload[:aud].join(', ')
if event.payload[:exception]
Rails.logger.warn("DIDWW token mint for #{aud} failed after #{event.duration.round} ms: #{event.payload[:exception].first}")
else
Rails.logger.info("DIDWW token minted for #{aud} in #{event.duration.round} ms")
end
end- Audience strategy. One token per audience, minted on first use, rather than one token naming every service. An account that never calls the prices services never requests their audiences, so a refused audience cannot break DID management, and every token is valid for one service only.
- Cache store. In-process memory by default, because Ruby processes serve many requests in their lifetime. A shared store is opt-in through
token_store. - Token lifetime. The longest the token service grants, one hour, so that a process mints each token as rarely as possible. Lifetime is decided by the server through the 401 refresh, not by a local expiry margin.
- Gzip handling. Price files are streamed to disk exactly as served, still gzipped and in binary mode, without being held in memory. The SDK never decompresses them on its own:
DIDWW::Prices.each_rowreads a downloaded file when you want rows. - Streamed-upload retry limitation. The 401 retry sends the request body a second time.
EncryptedFile.uploadrewinds its multipart body for that; when the file IO cannot be rewound (a pipe or a socket), the refused token is still discarded, but the 401 is not retried and the upload raisesDIDWW::Resource::EncryptedFile::UploadError. Pass aFile,TempfileorStringIOto keep the retry.
# Countries
countries = DIDWW::Client.countries.all
country = DIDWW::Client.countries.find('uuid')
# Regions, Cities, Areas
regions = DIDWW::Client.regions.all
cities = DIDWW::Client.cities.all
areas = DIDWW::Client.areas.all
# DID Groups (with stock keeping units), filtered by number type
did_groups = DIDWW::Client.did_groups
.where(number_type: DIDWW::Resource::DidGroup::NUMBER_TYPE_TOLL_FREE)
.includes(:stock_keeping_units)
.all
# Available DIDs (with DID group and stock keeping units)
available_dids = DIDWW::Client.available_dids
.includes('did_group.stock_keeping_units')
.all
# Public Keys
public_keys = DIDWW::Client.public_keys.all
# Address requirements
requirements = DIDWW::Client.address_requirements.all
# Balance (singleton)
balance = DIDWW::Client.balanceDidGroup, AddressRequirement, EmergencyRequirement and EmergencyCallingService carry a number_type, one of DIDWW::Resource::NumberTypes::NUMBER_TYPES (local, national, mobile, toll_free, shared_cost, global). DidGroup#is_demo flags demo groups.
# List DIDs
dids = DIDWW::Client.dids.all
# Update DID
did = DIDWW::Client.dids.find('uuid').first
did.description = 'Updated'
did.capacity_limit = 20
did.saveA DID's inbound messages go to an SMS trunk or to an SMS trunk group. The two are exclusive: assigning one clears the other in the same request, as voice_in_trunk and voice_in_trunk_group do.
did = DIDWW::Client.dids.find('uuid').first
did.sms_trunk = DIDWW::Resource::SmsTrunk.load(id: 'sms-trunk-uuid')
did.save # sends sms_trunk and sms_trunk_group: null
did.sms_trunk_group = DIDWW::Resource::SmsTrunkGroup.load(id: 'sms-trunk-group-uuid')
did.save # sends sms_trunk_group and sms_trunk: null
DIDWW::Client.dids.where('sms_trunk.id': 'sms-trunk-uuid').alltrunk = DIDWW::Client.voice_in_trunks.new(
name: 'My SIP Trunk',
pop: DIDWW::Resource::VoiceInTrunk::POP_AMS,
configuration: DIDWW::ComplexObject::SipConfiguration.new(
username: '{DID}',
host: 'sip.example.com',
port: 5060,
codecs: [
DIDWW::ComplexObject::SipConfiguration::CODEC_PCMA,
DIDWW::ComplexObject::SipConfiguration::CODEC_PCMU,
DIDWW::ComplexObject::SipConfiguration::CODEC_TELEPHONE_EVENT
],
ice_mode: DIDWW::ComplexObject::SipConfiguration::ICE_MODE_ACCEPT
)
)
trunk.savepop is a plain attribute, one of DIDWW::Resource::VoiceInTrunk::POPS (nyc, fra, lac, mia, sg, hk, ams). Leave it nil to let DIDWW choose.
codecs lists the codecs offered on calls to the trunk by name, in priority order: the first has the highest priority. It replaces codec_ids; the names are DIDWW::ComplexObject::SipConfiguration::CODECS. Left out, the trunk offers pcmu, pcma, g729, g723 and telephone_event. ice_mode, rtcp_mux_mode and rtcp_feedback_mode take disabled (the default), accept or initiate (ICE_MODES, RTCP_MUX_MODES and RTCP_FEEDBACK_MODES on SipConfiguration).
A Voice In Trunk can also be configured to authenticate inbound calls via SIP registration credentials generated by DIDWW. The SDK auto-cascades the dependent fields the server requires:
- setting
enabled_sip_registration = trueclears any previously-sethost/port(the server rejects them with 422 otherwise); - setting
hostto a non-blank value flipsenabled_sip_registrationback tofalseand forcesuse_did_in_ruri = falseso the server accepts the disable PATCH.
DIDWW generates incoming_auth_username and incoming_auth_password
and surfaces them in the response when SIP registration is enabled.
trunk = DIDWW::Client.voice_in_trunks.new(
name: 'Office (registered)',
configuration: DIDWW::ComplexObject::SipConfiguration.new.tap do |c|
c.enabled_sip_registration = true
c.use_did_in_ruri = true
c.cnam_lookup = true
end
)
trunk.save
# trunk.configuration.incoming_auth_username -- server-generated
# trunk.configuration.incoming_auth_password -- server-generatedTo disable SIP registration on an existing trunk, just set host —
the cascade flips enabled_sip_registration to false and
use_did_in_ruri to false automatically:
trunk.configuration = DIDWW::ComplexObject::SipConfiguration.new.tap do |c|
c.host = 'sip.example.com'
end
trunk.saveVoice Out Trunks use a polymorphic authentication_method (2026-04-16). Three types are supported:
credentials_and_ip-- default method;usernameandpasswordare server-generated and returned in the response.twilio-- requires atwilio_account_sid.ip_only-- read-only; can only be configured by DIDWW staff upon request. Cannot be set via the API.
# NOTE: 203.0.113.0/24 is RFC 5737 TEST-NET-3 documentation space.
# Replace with the real CIDR of your SIP infrastructure.
trunk = DIDWW::Client.voice_out_trunks.new(
name: 'My Outbound Trunk',
on_cli_mismatch_action: 'reject_call',
authentication_method: DIDWW::ComplexObject::AuthenticationMethod::CredentialsAndIp.new(
allowed_sip_ips: ['203.0.113.0/24']
),
codecs: [
DIDWW::Resource::VoiceOutTrunk::CODEC_OPUS,
DIDWW::Resource::VoiceOutTrunk::CODEC_PCMA,
DIDWW::Resource::VoiceOutTrunk::CODEC_TELEPHONE_EVENT
]
)
trunk.save
# trunk.authentication_method.username -- server-generated
# trunk.authentication_method.password -- server-generatedcodecs lists the codecs offered on calls from the trunk by name, in priority order: the first has the highest priority. The names are DIDWW::Resource::VoiceOutTrunk::CODECS, which differ from those of an inbound SIP trunk. Left out, the trunk offers pcma, pcmu and telephone_event. ice_mode, rtcp_mux_mode and rtcp_feedback_mode take disabled, accept (the default) or initiate (ICE_MODES, RTCP_MUX_MODES and RTCP_FEEDBACK_MODES on VoiceOutTrunk).
An SMS trunk delivers inbound messages, accepts outbound ones, or both. Its configuration is one of five types under DIDWW::ComplexObject::SmsTrunkConfiguration:
| Type | Class | Notes |
|---|---|---|
sms_to_email |
SmsToEmail |
Inbound messages are forwarded as email. send_to, subject and message are required. |
http_in |
HttpIn |
Inbound messages are sent as an HTTP request to your url. http_method is one of HttpIn::HTTP_METHODS; post and put also need body_type (one of HttpIn::BODY_TYPES) and body. |
http_out |
HttpOut |
You submit outbound messages over HTTP. auth_name and auth_password are generated. The submit URL is trunk.host. |
smpp_esme |
SmppEsme |
You bind to DIDWW as an SMPP ESME. server_location is required; system_id and password are generated. |
smpp_smsc |
SmppSmsc |
DIDWW binds to your SMSC with your host, system_id, password and server_location. |
The read-only allow_in and allow_out tell which directions a trunk handles. server_location is one of SmsTrunkConfiguration::SERVER_LOCATIONS; the sandbox accepts nyc only. A configuration type this gem does not know is read as SmsTrunkConfiguration::Generic and sent back unchanged.
configurations = DIDWW::ComplexObject::SmsTrunkConfiguration
trunk = DIDWW::Client.sms_trunks.new(
name: 'Inbound webhook',
configuration: configurations::HttpIn.new(
url: 'https://example.com/sms',
http_method: configurations::HttpIn::HTTP_METHOD_POST,
body_type: configurations::HttpIn::BODY_TYPE_JSON,
body: '{"text":"{SMS_TEXT}","from":"{SMS_SRC_ADDR}","to":"{SMS_DST_ADDR}"}'
)
)
trunk.save
# On update the configuration type must stay the same; attributes left out keep their values.
trunk.configuration = configurations::HttpIn.new(url: 'https://example.com/sms/v2')
trunk.save
# List by configuration type, with the group
DIDWW::Client.sms_trunks.where('configuration.type': 'http_in,sms_to_email').includes(:sms_trunk_group).allThe generated credentials of http_out and smpp_esme trunks are read-only and are never sent back on update. They are redacted in #inspect, as are the headers of an http_in configuration, which may carry the credentials of your endpoint, and every value of a configuration type this gem version does not know (Generic). To rotate them:
trunk = DIDWW::Client.sms_trunks.find('uuid').first
trunk.regenerate_credentials # POST /sms_trunk_regenerate_credentials
trunk = DIDWW::Client.sms_trunks.find(trunk.id).first
trunk.configuration.password # the new passwordAn SMS trunk group spreads a DID's inbound messages over its trunks by their priority. http_out trunks cannot join a group. Deleting a group also deletes the trunks in it.
group = DIDWW::Client.sms_trunk_groups.new(name: 'Inbound SMS')
group.relationships.sms_trunks = [DIDWW::Resource::SmsTrunk.load(id: 'sms-trunk-uuid')]
group.save
group.sms_trunks_count # => 1A Sender ID verification covers the sender IDs your outbound messages use. It is created and reviewed outside the API: the API lists and reads verifications, and changes only their name and the SMS trunk their messages are routed through. A closed verification cannot be changed. status is one of SenderIdVerification::STATUSES and sender_type one of SenderIdVerification::SENDER_TYPES; meta carries setup_price and monthly_price as decimal strings.
verifications = DIDWW::Client.sender_id_verifications
.where(status: DIDWW::Resource::SenderIdVerification::STATUS_ACTIVE)
.includes(:sms_trunk)
.all
verification = verifications.first
verification.sms_trunk = DIDWW::Resource::SmsTrunk.load(id: 'sms-trunk-uuid') # http_out, smpp_esme or smpp_smsc
verification.save
verification.sms_trunk = nil # outbound messages stop until a trunk is assigned again
verification.saveDeleting an SMS trunk leaves the verifications routed through it without a trunk.
export = DIDWW::Client.exports.new(
export_type: DIDWW::Resource::Export::EXPORT_TYPE_SMS_OUT,
filters: DIDWW::ComplexObject::ExportFilters.new(
from: '2026-10-01 00:00:00', # inclusive
to: '2026-10-02 00:00:00', # exclusive
service_type: DIDWW::ComplexObject::ExportFilters::SERVICE_TYPE_A2P,
sms_trunk_id: ['sms-trunk-uuid'] # sent as "sms_trunk.id"
)
)
export.save
# Once export.completed?
file = export.download # binary Tempfile with the gzipped CSV
csv = export.csv # StringIO with the decompressed CSVdownload and csv send the API bearer token, so they accept only a url on the scheme, host and port of the API base URL or of the canonical API URL of api_mode, which the API builds export urls from even when DIDWW_API_URL points elsewhere. They raise ArgumentError for any other, without sending a request.
from and to are required for every export type. The other filter keys depend on export_type (cdr_in, cdr_out, sms_in, sms_out); see DIDWW::ComplexObject::ExportFilters. sms_trunk_id, sender_id_verification_id and voice_out_trunk_id are sent as the dotted keys sms_trunk.id, sender_id_verification.id and voice_out_trunk.id.
Filter values are lowercase: service_type is a2p or p2p (ExportFilters::SERVICE_TYPES), trunk_type is one or more of smpp_smsc, smpp_esme, sms_to_email and http_in (ExportFilters::TRUNK_TYPES), and status is success, failed or queued for sms_in, and routing_error, in_progress, queued, failed or success for sms_out.
order = DIDWW::Client.orders.new(
items: [
DIDWW::ComplexObject::DidOrderItem.new(sku_id: 'sku-uuid', qty: 2)
]
)
order.save# List emergency requirements with filters
requirements = DIDWW::Client.emergency_requirements
.includes(:country)
.all
# Filter by country and number type
requirements = DIDWW::Client.emergency_requirements
.where('country.id': 'country-uuid', number_type: 'local')
.all
requirements.each do |req|
puts req.identity_type
puts req.address_area_level
puts req.estimate_setup_time # e.g. "7-14 days"
puts req.requirement_restriction_message
end
# Create an emergency verification; relationships go under relationships:
verification = DIDWW::Client.emergency_verifications.new(
external_reference_id: 'my-ref-123',
relationships: {
address: DIDWW::Resource::Address.load(id: 'address-uuid'),
emergency_calling_service:
DIDWW::Resource::EmergencyCallingService.load(id: 'ecs-uuid'),
dids: [DIDWW::Resource::Did.load(id: 'did-uuid')]
}
)
if verification.save
puts "Created: #{verification.id} (status: #{verification.status})"
else
puts "Errors: #{verification.errors.full_messages}"
end
# List emergency calling services
services = DIDWW::Client.emergency_calling_services
.includes(:country, :dids)
.all
services.each do |svc|
puts "#{svc.name} — #{svc.status} (#{svc.number_type})"
end
# Cancel (destroy) an emergency calling service
svc = DIDWW::Client.emergency_calling_services.find('uuid').first
svc.destroy# List recent DID history events (retained for the last 90 days)
events = DIDWW::Client.did_history.all
events.each do |event|
puts "#{event.created_at.iso8601} #{event.did_number} #{event.action} via #{event.method}"
end
# Filter by action
assigned = DIDWW::Client.did_history
.where(action: DIDWW::Resource::DidHistory::ACTION_ASSIGNED)
.all
# Filter by DID number
per_number = DIDWW::Client.did_history
.where(did_number: '12125551234')
.all
# Filter by date range
seven_days_ago = (Time.now - 7 * 24 * 60 * 60).iso8601
recent = DIDWW::Client.did_history
.where(created_at_gteq: seven_days_ago)
.allPrices are served by three services outside the JSON:API (hosts in Environments). Each price list has a price file and a lookup:
| Accessor | Service | Price file | Lookup | Lookup rows |
|---|---|---|---|---|
DIDWW::Client.voice_in_prices |
Voice IN | prices.csv.gz |
lookup/prices |
DIDWW::Prices::VoiceInPrice |
DIDWW::Client.voice_out_prices |
Voice OUT | prices.csv.gz |
lookup/prices |
DIDWW::Prices::VoiceOutPrice |
DIDWW::Client.sms_out_a2p_prices |
SMS | sms_out/a2p/prices.csv.gz |
sms_out/a2p/lookup/prices |
DIDWW::Prices::SmsOutPrice |
DIDWW::Client.sms_out_p2p_prices |
SMS | sms_out/p2p/prices.csv.gz |
sms_out/p2p/lookup/prices |
DIDWW::Prices::SmsOutPrice |
DIDWW::Client.sms_out_otp_prices |
SMS | sms_out/otp/prices.csv.gz |
sms_out/otp/lookup/prices |
DIDWW::Prices::SmsOutPrice |
DIDWW::Client.sms_in_prices |
SMS | sms_in/prices.csv.gz |
sms_in/lookup/prices |
DIDWW::Prices::SmsInPrice |
Each accessor returns a DIDWW::Prices::Service. The account needs a price plan of that service: without one, every call raises DIDWW::Prices::PricePlanNotAssigned.
result = DIDWW::Client.voice_in_prices.lookup(number: '18005550123', src_country_iso: 'US')
result.total_records
result.each do |price|
puts "#{price.destination} #{price.source_type}: #{price.rate&.to_s('F')} USD/min"
end
DIDWW::Client.voice_out_prices.lookup(number: '493012345678').first.category
DIDWW::Client.sms_out_a2p_prices.lookup(dst_number: '4915123456789')
DIDWW::Client.sms_in_prices.lookup(dst_country_iso: 'US')| Service | Filters |
|---|---|
| Voice IN | number (required), src_country_iso |
| Voice OUT | number (required); no other filter |
| SMS OUT and SMS IN | dst_number, dst_country_iso; at least one |
A missing or unknown filter raises ArgumentError before any request; blank values are dropped. The server checks the value formats and answers a bad value with 400 (DIDWW::Prices::BadRequest).
lookup returns a DIDWW::Prices::LookupResult, an Enumerable of price objects with total_records and size. Prices and fees are BigDecimal, VoiceOutPrice#effective_at is a Time, and #to_h returns every attribute. VoiceOutPrice#category is one of DIDWW::Prices::VoiceOutPrice::CATEGORIES.
The id of an SMS OUT or SMS IN lookup row is derived from its content: it changes when the row or its price changes, so do not use it to track a destination over time. A Voice OUT id names the answer by the plan, the prefix and the routing conditions, and stays the same when a re-import changes only the price. A Voice IN id names the answering row of the plan.
The files are gzipped CSV. The SDK writes them exactly as served and never decompresses them.
prices = DIDWW::Client.voice_out_prices
# Download unless the copy at the path is current
file = prices.fetch('/var/data/voice_out_prices.csv.gz')
file.modified? # true: downloaded; false: answered 304, the file was kept
file.last_modified # Time
file.bytes_written
# Read the rows
DIDWW::Prices.each_row('/var/data/voice_out_prices.csv.gz') do |row|
puts "#{row['Prefix']}: #{row['Rate']}"
end
# Lower-level calls
status = prices.head(if_modified_since: file.last_modified)
status.not_modified?
status.content_length
status.filename # from Content-Disposition, e.g. "voice_out_prices.csv.gz"
prices.download(to: '/tmp/voice_out_prices.csv.gz')
File.open('/tmp/copy.csv.gz', 'wb') { |io| prices.download(to: io) }fetch(path)sends the modification time of the file atpathasIf-Modified-Since, when the file is there. A file written bydownload(to: path)orfetchgets theLast-Modifiedof the response as its modification time, so the date matches the copy on disk.fetchtrusts the modification time of any file atpath: a file copied or changed by other means can be answered 304 and kept, so replace such a file withdownload(to: path).download(to:)streams the body into an IO, or into a temp file.didww-<16 hex digits>.tmpin the directory ofpath, unique to the call, that is synced to disk and replacespathonly on a 200. A 304 or an error leaves an existing file untouched, and concurrent downloads to one path do not mix their bytes. An IO target receives the body as it arrives, so after an error it may hold part of it.headanddownloadreturn aDIDWW::Prices::PriceFile:status,last_modified,content_length,filename,bytes_written,modified?andnot_modified?.- The files have a header row, and
each_rowyields each row by its column names. Prices are in USD with VAT excluded. Voice IN: Country, Src country name, Source type, Destination, Rate, Connection fee, Initial interval, Next interval and Reject calls. Voice OUT: Category, Country, Network, Prefix (one prefix per row), Rate, Connection fee, Initial increment, Recurring increment, Reject calls, Next rate, Next connection fee, Next initial increment, Next recurring increment, Effective date and Comment. SMS OUT: Source prefix, Destination prefix, Country, MCC, MCC name, MNC, MNC name, Reject SMS (trueorfalse) and Price. SMS IN: Source prefix, Source number length min, Source number length max, Destination prefix, Destination number length min, Destination number length max, Country and Price. - Only
Last-ModifiedandIf-Modified-Sinceare used. The service sends noETag, and the SDK never sendsIf-None-Match, which would make the service ignoreIf-Modified-Since. - A 503 on a price file is retried up to 2 times when its
Retry-Afteris 60 seconds or less, after waiting that long, at least 1 second, plus a random delay of up to a fifth of that wait (at least up to 1 s) so that clients do not retry in step. Otherwise it raisesDIDWW::Prices::ServiceUnavailablewithretry_after. - Redirects are not followed. Any status the API does not document for the call, such as a 3xx or a 202, raises
DIDWW::Prices::UnexpectedStatus. An error is never turned into an empty file or an empty result.
See
FILTERS.mdfor the list offilter[KEY]keys accepted by every list endpoint at API version2026-11-19.
The SDK uses json_api_client which raises exceptions for HTTP-level errors. Validation errors from the API are returned on the resource's errors collection after a failed save.
# Validation errors (422 Unprocessable Entity)
trunk = DIDWW::Client.voice_in_trunks.new(
name: 'Office',
ringing_timeout: 100, # more than the allowed 32 seconds
configuration: DIDWW::ComplexObject::SipConfiguration.new(host: 'sip.example.com')
)
unless trunk.save
trunk.errors.full_messages.each do |msg|
puts "Validation error: #{msg}"
end
end
# HTTP errors
begin
DIDWW::Client.dids.find('nonexistent-uuid')
rescue JsonApiClient::Errors::NotFound => e
puts "Not found: #{e.message}"
rescue JsonApiClient::Errors::NotAuthorized => e
puts "Token refused twice: #{e.message}"
rescue JsonApiClient::Errors::AccessDenied => e
puts "Access denied (e.g. a write with a read token): #{e.message}"
rescue JsonApiClient::Errors::TooManyRequests => e
puts "Rate limited, retry in #{e.retry_after.inspect} s: #{e.message}"
rescue JsonApiClient::Errors::ServerError => e
puts "Server error: #{e.message}"
rescue JsonApiClient::Errors::ConnectionError => e
puts "Connection error: #{e.message}"
rescue DIDWW::Auth::Error => e
puts "No access token: #{e.message} (status #{e.status}, retry after #{e.retry_after.inspect})"
endExport#download raises the same JsonApiClient::Errors classes. It does not follow redirects: any status other than 200, such as a 3xx or 204, raises JsonApiClient::Errors::UnexpectedStatus.
A 429 (too_many_requests) means the request budget of the account for the current window is spent. Resource calls and Export#download raise it as DIDWW::TooManyRequests, a JsonApiClient::Errors::TooManyRequests whose retry_after is the Retry-After of the response in seconds (nil when it is missing or is an HTTP date). The SDK does not retry it, as a write may not be safe to send twice: wait retry_after seconds before sending the request again. EncryptedFile.upload raises DIDWW::Resource::EncryptedFile::UploadError for any status other than 201, with the status of the response; on a 429 its retry_after is the Retry-After in seconds (nil when it is missing or is an HTTP date), and the upload is not retried either.
Errors raised by the SDK itself inherit from DIDWW::Error, except DIDWW::TooManyRequests described above.
Token service (DIDWW::Auth::Error, with status, error, error_description and retry_after). They are raised from any call that needs a new token:
| Class | Raised when |
|---|---|
DIDWW::Auth::InvalidClient |
401: the API key is missing, unknown or disabled, or the caller's IP is not allowed. Not retried. |
DIDWW::Auth::InvalidRequest |
400 invalid_request or invalid_scope. |
DIDWW::Auth::RateLimited |
429. retry_after is the token service's Retry-After in seconds, at least 1. The SDK keeps refusing mints for a random extra of up to a fifth of it (at least up to 1 s) on top of it, and a mint refused in that window raises RateLimited with the seconds left, so retry in a loop rather than once. |
DIDWW::Auth::ServerError |
5xx on every attempt. |
DIDWW::Auth::ConnectionError |
Connection failure or timeout on every attempt, or a TLS failure. |
DIDWW::Auth::InvalidGrant |
The token does not cover the requested audience. |
DIDWW::Auth::Error |
Any other status. |
Prices (DIDWW::Prices::Error, with status, code, errors and retry_after):
| Class | Status |
|---|---|
DIDWW::Prices::BadRequest |
400, e.g. a filter value of the wrong format |
DIDWW::Prices::NotAuthorized |
401 after the token was replaced once |
DIDWW::Prices::AccessDenied |
403 |
DIDWW::Prices::PricePlanNotAssigned |
404 price_plan_not_assigned; also any 404 on head, which has no body |
DIDWW::Prices::PriceNotFound |
404 price_not_found: no price matches the lookup |
DIDWW::Prices::NotAcceptable |
406 |
DIDWW::Prices::TooManyRequests |
429, with retry_after. Not retried. |
DIDWW::Prices::ServiceUnavailable |
503, with retry_after. Retried on price files only, see Price files. |
DIDWW::Prices::UnexpectedStatus |
Any other status |
DIDWW::Prices::ConnectionError |
Connection failure, timeout or TLS failure. Not retried. An error writing the file or IO is raised as it is. |
The SDK (via json_api_client) tracks which attributes have been modified. When you call save on a fetched resource, the resulting PATCH request sends only the changed attributes, avoiding unintended overwrites of server-side values.
did = DIDWW::Client.dids.find('uuid').first
did.description = 'Updated'
did.save
# PATCH payload includes only "description", not all attributesThe SDK distinguishes between date-only and datetime fields:
- Datetime fields — deserialized as
Time:created_at— present on most resourcesupdated_at—SmsTrunk,SmsTrunkGroupexpires_at—Did,DidReservation,Proof,EncryptedFile(nullable)activated_at—EmergencyCallingService,SenderIdVerification(nullable)canceled_at—EmergencyCallingService(nullable)closed_at—SenderIdVerification(nullable)effective_at—DIDWW::Prices::VoiceOutPrice(nullable)
- Date-only fields — kept as the
Stringthe API sends,"YYYY-MM-DD"; useDate.iso8601when aDateis needed:CapacityPool#renew_dateEmergencyCallingService#renew_date,SenderIdVerification#renew_date,Identity#birth_date(nullable)
- String fields (not numeric):
EmergencyRequirement#estimate_setup_time— e.g."7-14 days","1"EmergencyRequirement#requirement_restriction_message— nullable
Important changes from previous API versions:
expire_atrenamed toexpires_atonDidReservationandEncryptedFilerenew_dateis a date-only string, NOT a datetimeestimate_setup_timeis a string, NOT an integer
did = DIDWW::Client.dids.find("uuid").first
puts did.created_at # => 2024-01-15 10:00:00 UTC (Time)
puts did.expires_at # => nil or 2025-01-15 10:00:00 UTC (Time)
identity = DIDWW::Client.identities.find("uuid").first
puts identity.birth_date # => 1990-05-20 (String)See docs/resource_relationships.md for a Mermaid ER diagram showing all has_one, has_many, and belongs_to relationships between resources.
Validate incoming webhook callbacks from DIDWW using HMAC-SHA1 signature verification.
Initialize the validator with the callback secret that is enabled in the DIDWW User Panel (APIs → DIDWW API 3 → Callback Secrets). DIDWW signs every callback with it and sends callbacks only while a callback secret is enabled.
require 'didww/callback/request_validator'
validator = DIDWW::Callback::RequestValidator.new("YOUR_CALLBACK_SECRET")
# In your webhook handler:
valid = validator.validate(
request_url, # full original URL
payload_params, # Hash of payload key-value pairs
signature # value of X-DIDWW-Signature header
)The signature header name is available as the constant DIDWW::Callback::RequestValidator::HEADER.
class WebhooksController < ApplicationController
skip_before_action :verify_authenticity_token
def create
validator = DIDWW::Callback::RequestValidator.new("YOUR_CALLBACK_SECRET")
signature = request.headers[DIDWW::Callback::RequestValidator::HEADER]
params_hash = request.POST
if validator.validate(request.original_url, params_hash, signature)
# Process the webhook
head :ok
else
head :forbidden
end
end
endThe SDK provides constants for all API option fields. These are defined as constants on their respective modules/classes:
CallbackMethod, IdentityType, OrderStatus, ExportType, ExportStatus, CliFormat,
OnCliMismatchAction*, MediaEncryptionMode, DefaultDstAction, VoiceOutTrunkStatus,
EmergencyCallingServiceStatus, EmergencyVerificationStatus, DiversionRelayPolicy,
TransportProtocol, Codec, RxDtmfFormat, TxDtmfFormat, SstRefreshMethod,
ReroutingDisconnectCode, Feature, AreaLevel, AddressVerificationStatus, StirShakenMode,
NumberType, Pop, ExportSmsTrunkType, ExportSmsServiceType, SmsHttpMethod, SmsBodyType,
SmsServerLocation, VoiceOutPriceCategory, SenderIdVerificationStatus, SenderIdVerificationSenderType,
IceMode, RtcpMuxMode, RtcpFeedbackMode
* REPLACE_CLI and RANDOMIZE_CLI require additional account configuration. Contact DIDWW support to enable these values.
The constants for NumberType, Pop, ExportSmsTrunkType, ExportSmsServiceType, SmsHttpMethod, SmsBodyType, SmsServerLocation, VoiceOutPriceCategory, SenderIdVerificationStatus and SenderIdVerificationSenderType are DIDWW::Resource::NumberTypes::NUMBER_TYPES, DIDWW::Resource::VoiceInTrunk::POPS, DIDWW::ComplexObject::ExportFilters::TRUNK_TYPES and SERVICE_TYPES, DIDWW::ComplexObject::SmsTrunkConfiguration::HttpIn::HTTP_METHODS and BODY_TYPES, DIDWW::ComplexObject::SmsTrunkConfiguration::SERVER_LOCATIONS, DIDWW::Prices::VoiceOutPrice::CATEGORIES, and DIDWW::Resource::SenderIdVerification::STATUSES and SENDER_TYPES.
Codec, IceMode, RtcpMuxMode and RtcpFeedbackMode are CODECS, ICE_MODES, RTCP_MUX_MODES and RTCP_FEEDBACK_MODES, with one constant per value (CODEC_PCMA, ICE_MODE_ACCEPT, ...), on DIDWW::ComplexObject::SipConfiguration for inbound SIP trunks and on DIDWW::Resource::VoiceOutTrunk for outbound trunks. The two codec lists differ.
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 tags, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/didww/didww-v3-ruby.
The gem is available as open source under the terms of the MIT License.