Sendly Ruby SDK

require 'sendly'

# Create a client
client = Sendly::Client.new("sk_live_v1_your_api_key")

# Send an SMS
message = client.messages.send(
  to: "+15125550123",
  text: "Hello from Sendly!"
)

puts message.id     # => "msg_abc123"
puts message.status # => "queued"

Sendly.configure do |config|
  config.api_key = "sk_live_v1_xxx"
end

# Use the default client
Sendly.send_message(to: "+15125550123", text: "Hello!")

client = Sendly::Client.new(
  "sk_live_v1_xxx",
  base_url: "https://sendly.live/api/v1",
  timeout: 60,
  max_retries: 5,
  organization_id: "org_abc"   # sent as X-Organization-Id; defaults to ENV["SENDLY_ORG_ID"]
)

# The API key is also accepted as a keyword, for callers on the older signature.
client = Sendly::Client.new(api_key: "sk_live_v1_xxx")

# Marketing message (default)
message = client.messages.send(
  to: "+15125550123",
  text: "Check out our new features!"
)

# Transactional message (bypasses quiet hours)
message = client.messages.send(
  to: "+15125550123",
  text: "Your verification code is: 123456",
  message_type: "transactional"
)

# With custom metadata (max 4KB)
message = client.messages.send(
  to: "+15125550123",
  text: "Your order #12345 has shipped!",
  metadata: { order_id: "12345", customer_id: "cust_abc" }
)

# Send from one of your owned numbers (or an alphanumeric sender ID).
# Omit `from` to use your default sender.
message = client.messages.send(
  to: "+15125550123",
  text: "Hello from our team!",
  from: "+447700900123"
)

puts message.id
puts message.status
puts message.credits_used

# Basic listing
messages = client.messages.list(limit: 50)
messages.each { |m| puts m.to }

# With filters
messages = client.messages.list(
  status: "delivered",
  to: "+15125550123",
  limit: 20,
  offset: 0
)

# Pagination info: total counts every matching message, not just this page
puts messages.total
puts messages.has_more

message = client.messages.get("msg_abc123")

puts message.to
puts message.text
puts message.status
puts message.delivered_at

# Schedule a message for future delivery
scheduled = client.messages.schedule(
  to: "+15125550123",
  text: "Your appointment is tomorrow!",
  scheduled_at: (Time.now.utc + 3600).iso8601  # 5 minutes to 5 days ahead
)

# schedule returns the raw Hash the API sent, not a Message object
puts scheduled["id"]
puts scheduled["scheduledAt"]

# List scheduled messages (returns a Hash with "data" array)
result = client.messages.list_scheduled
result["data"].each { |msg| puts "#{msg['id']}: #{msg['scheduledAt']}" }

# Get a specific scheduled message
msg = client.messages.get_scheduled("schd_xxx")

# Cancel a scheduled message (refunds credits)
result = client.messages.cancel_scheduled("schd_xxx")
puts "Refunded: #{result['creditsRefunded']} credits"

# Send multiple messages in one API call (up to 10,000)
batch = client.messages.send_batch(
  messages: [
    { to: "+15125550123", text: "Hello User 1!" },
    { to: "+15125550124", text: "Hello User 2!" },
    { to: "+15125550125", text: "Hello User 3!" }
  ]
)

puts batch["batchId"]
puts "Status: #{batch['status']}"        # "processing" until the batch finishes
puts "Sent: #{batch['sent']}"
puts "Failed: #{batch['failed']}"
puts "Credits used: #{batch['creditsUsed']}"

# Get batch status. The stored batch — unlike the send response — also
# carries queued/delivered counts.
status = client.messages.get_batch("batch_xxx")
puts "#{status['queued']} queued, #{status['delivered']} delivered"

# List all batches
batches = client.messages.list_batches

# Preview batch (dry run) - validates without sending
preview = client.messages.preview_batch(
  messages: [
    { to: '+15125550123', text: 'Hello User 1!' },
    { to: '+447700900123', text: 'Hello UK!' }
  ]
)
puts "Credits needed: #{preview['creditsNeeded']} (balance #{preview['creditBalance']})"
puts "Sendable: #{preview['sendable']} of #{preview['total']}, blocked: #{preview['blocked']}"
puts "Enough credits? #{preview['hasSufficientCredits']}"

# Auto-pagination
client.messages.each do |message|
  puts "#{message.id}: #{message.to}"
end

# With filters
client.messages.each(status: "delivered") do |message|
  puts "Delivered: #{message.id}"
end

group = client.messages.send_group(
  to: ["+14155550123", "+14155550124"],
  text: "Hey team - quick sync at noon?"
)

puts group.id                # => "msg_abc123"
puts group.group_message_id  # => "grp_..." (present on live sends)
puts group.status            # => "sent" (or "delivered" when simulated)
puts group.simulated?        # => true on test keys / before verification

# Recipients: on a live send each entry is a Hash with the per-recipient
# status ({ "phoneNumber" => "+14155550123", "status" => "queued" });
# on a simulated send each entry is the phone number String.
group.to.each { |r| puts r.is_a?(Hash) ? "#{r['phoneNumber']} #{r['status']}" : r }

# With media instead of (or in addition to) text
client.messages.send_group(
  to: ["+14155550123", "+14155550124"],
  media_urls: ["https://cdn.acme.example/flyer.jpg"],
  message_type: "marketing"
)

result = client.messages.enhance(
  text: "hey come check out our sale this weekend",
  message_type: "marketing"
)

puts result.enhanced     # polished, ≤160-char rewrite
puts result.explanation  # what changed and why
puts result.model        # model used (when available)

message = client.messages.send(
  to: "+15125550123",
  text: "Your order has shipped!",
  idempotency_key: "order-4821-shipped"
)

# Create a webhook endpoint
webhook = client.webhooks.create(
  url: "https://acme.example/webhooks/sendly",
  events: ["message.delivered", "message.failed"]
)

puts webhook.id
puts webhook.secret  # Store securely!

# List all webhooks
webhooks = client.webhooks.list

# Get a specific webhook
wh = client.webhooks.get("whk_xxx")

# Update a webhook
client.webhooks.update("whk_xxx",
  url: "https://new-endpoint.acme.example/webhook",
  events: ["message.delivered", "message.failed", "message.sent"]
)

# Test a webhook. A delivered test returns a Sendly::WebhookTestResult; a
# test your endpoint fails raises Sendly::ValidationError with the API's
# message ("Test webhook failed: ...").
result = client.webhooks.test("whk_xxx")
puts "#{result.status_code} in #{result.response_time_ms}ms (#{result.delivery_id})"

# Rotate webhook secret. Deliveries are signed with the new secret from
# the moment it is issued and the old secret is not kept, so switch your
# endpoint over straight away. new_secret is shown only once.
rotation = client.webhooks.rotate_secret("whk_xxx")
puts rotation.new_secret
puts rotation.new_secret_version

# Delete a webhook
client.webhooks.delete("whk_xxx")

# Delivery history, newest first (limit defaults to 50, max 100), and a
# manual retry of one delivery
client.webhooks.deliveries("whk_xxx", status: "failed", limit: 20).each do |d|
  puts "#{d.event_type} #{d.status} (attempt #{d.attempt_number}/#{d.max_attempts})"
end
client.webhooks.retry_delivery("whk_xxx", "del_xxx")

# Event types the API describes (a subset: subscribe accepts every
# Sendly::Webhooks::EVENT_* constant except EVENT_MESSAGE_QUEUED)
client.webhooks.event_types.each { |t| puts t }

client.webhooks.reset_circuit("whk_xxx")

# Re-fire deliveries we recorded but could not deliver
client.webhooks.redeliver("whk_xxx",
  since: (Time.now.utc - 86_400).iso8601,
  event_types: ["message.delivered"],
  statuses: ["failed", "cancelled"],   # default
  limit: 1000)                         # default 1000, max 10000

# Synthesize events that never got an audit row at all (what redeliver
# cannot recover). A synthesized event reuses the id the original dispatch
# used, so dedupe on event.id. Not on event.data.object.id: a message's
# sent and delivered events share it.
client.webhooks.backfill("whk_xxx", since: (Time.now.utc - 86_400).iso8601)

event = Sendly::Webhooks.parse_event(
  request.raw_post,
  request.headers["X-Sendly-Signature"],
  ENV.fetch("SENDLY_WEBHOOK_SECRET"),
  timestamp: request.headers["X-Sendly-Timestamp"]
)

case event.type
when Sendly::Webhooks::EVENT_MESSAGE_DELIVERED
  # message.* events also get a typed message view
  puts "#{event.message.id} -> #{event.message.to}"
when Sendly::Webhooks::EVENT_RCS_AGENT_LIVE
  puts event.data[:agent_id]
  puts event.data.stage
when Sendly::Webhooks::EVENT_CALL_COMPLETED
  puts event.data[:duration_secs]
end

# Or read data.object as a type of your own. A Struct or Data class is filled
# from the members it declares and ignores the rest of the payload, so a field
# added to the event later cannot break the call.
AgentLive = Struct.new(:agent_id, :name, :stage)
agent = event.object_as(AgentLive)

require "sendly"

# Framework-neutral: hand it the raw request body and a headers Hash.
def handle_sendly_webhook(raw_body, headers)
  event = Sendly::Webhooks.parse_event(
    raw_body,
    headers["X-Sendly-Signature"],
    ENV.fetch("SENDLY_WEBHOOK_SECRET"),
    timestamp: headers["X-Sendly-Timestamp"]
  )

  case event.type
  when Sendly::Webhooks::EVENT_RCS_AGENT_LIVE
    # data.object is the agent: agent_id, name, stage
    puts "RCS agent #{event.data[:name]} is #{event.data.stage}"
    puts event.data[:agent_id]
  when Sendly::Webhooks::EVENT_NUMBER_ACTIVATED
    # data.object is the number: id, phone, status, country_code, source
    puts "#{event.data[:phone]} active in #{event.data[:country_code]}"
  when Sendly::Webhooks::EVENT_CONTACT_AUTO_FLAGGED
    # the contact is `id`; the message that failed is `message_id`
    puts "flagged #{event.data[:id]} (#{event.data[:invalid_reason]})"
    puts "from message #{event.data[:message_id]}"
  when Sendly::Webhooks::EVENT_MESSAGE_DELIVERED
    # message.* events, and only these, also get the typed message view
    puts "#{event.message.id} delivered to #{event.message.to}"
  else
    # An event type this SDK predates still parses; raw_object holds all of it.
    puts "unhandled #{event.type}: #{event.raw_object.inspect}"
  end

  :ok
rescue Sendly::WebhookSignatureError
  :unauthorized
end

event.data.from
# => NoMethodError: undefined method 'from' for Sendly::WebhookObject:
#    this event's data.object carries agent_id, name, stage, organization_id
event.message      # => nil
event.message.id   # => NoMethodError — nil has no #id

# Get account information. name is the workspace's name; organization,
# credits, verification, api_key and limits are the API's Hashes as sent.
account = client.account.get
puts account.email
puts "#{account.name} (#{account.organization_id})"
puts account.verification&.dig("status")

# Check credit balance (a Sendly::Credits object, not a Hash)
credits = client.account.credits
puts "Available: #{credits.available_balance} credits"
puts "Reserved: #{credits.reserved_balance} credits"
puts "Total: #{credits.balance} credits"

# View credit transaction history
transactions = client.account.transactions
transactions.each do |tx|
  puts "#{tx.type}: #{tx.amount} credits - #{tx.description}"
end

# List API keys
keys = client.account.api_keys
keys.each do |key|
  puts "#{key.name}: #{key.prefix} (#{key.type})"
end

# Create a new API key. type: is "test" (the default) or "live"; scopes:
# defaults to every scope the calling key has and cannot go beyond them.
# A live key needs a verified business and credits: the API answers 403
# verification_required or 402 credits_required otherwise.
result = client.account.create_api_key('Production Key', type: 'live', scopes: ['sms:send', 'sms:read'])
puts "New key: #{result['key']}"  # Only shown once!

# Rotate an API key. Issues a new key and keeps the old one valid for a grace
# period (default 24h; 24-168 allowed) so you can deploy before the old expires.
rotation = client.account.rotate_api_key('key_xxx', grace_period_hours: 72)
puts "New key: #{rotation['newKey']['key']}"  # Only shown once!
puts rotation['message']                      # "Old key will expire in 72 hours"

# Revoke an API key (an optional reason is recorded on the key's audit trail)
client.account.revoke_api_key('key_xxx', reason: 'rotated out of CI')

# Fetch one key, and its usage statistics
key = client.account.api_key('key_xxx')
puts "#{key.name}: #{key.scopes.join(', ')}#{key.revoked? ? ' (revoked)' : ''}"
usage = client.account.api_key_usage('key_xxx')

# Move credits to another workspace you own
client.account.transfer_credits(target_organization_id: 'org_xyz', amount: 500)

# Create a contact
contact = client.contacts.create(
  phone_number: "+15125550123",
  name: "Alice Example",
  email: "alice@acme.example",
  metadata: { plan: "pro" }
)

# List / search (scope to a list with list_id:)
result = client.contacts.list(limit: 50, search: "alice")
result[:contacts].each { |c| puts "#{c.name}: #{c.phone_number}" }
puts result[:total]

# Get, update, delete
c = client.contacts.get(contact.id)
client.contacts.update(contact.id, name: "Alice E.")  # see the note below
client.contacts.delete(contact.id)

# A contact's helper flags
puts c.opted_out?  # excluded from marketing sends
puts c.invalid?    # auto-flagged as unreachable (landline / bad number)

# Bulk import (dedupes by phone; each entry is a Hash)
report = client.contacts.import_contacts(
  [
    { phone: "+15125550123", name: "Alice" },
    { phone: "+15125550124", name: "Bob", email: "bob@acme.example" }
  ],
  list_id: "list_abc"
)
puts "Imported #{report[:imported]}, skipped #{report[:skipped_duplicates]}, errors #{report[:total_errors]}"

# Clear the auto-invalid flag (single or bulk). bulk_mark_valid takes
# either ids: (up to 10,000) or list_id: — not both.
client.contacts.mark_valid("contact_1")
client.contacts.bulk_mark_valid(list_id: "list_abc")
report = client.contacts.bulk_mark_valid(ids: ["contact_1", "contact_2"])
puts "Cleared #{report[:cleared]}"

# Trigger a carrier line-type lookup (async; landlines get excluded)
client.contacts.check_numbers(list_id: "list_abc", force: false)

# Create and manage lists
list = client.contacts.lists.create(name: "VIP Customers", description: "Top spenders")
all = client.contacts.lists.list
all[:lists].each { |l| puts "#{l.name} (#{l.contact_count})" }

# Get a list (paginate its members)
detail = client.contacts.lists.get(list.id, limit: 100, offset: 0)

client.contacts.lists.update(list.id, name: "VIPs")

# Add / remove members
result = client.contacts.lists.add_contacts(list.id, ["contact_1", "contact_2"])
puts "Added #{result[:added_count]}"
client.contacts.lists.remove_contact(list.id, "contact_1")

client.contacts.lists.delete(list.id)

# Create a campaign
campaign = client.campaigns.create(
  name: "Spring Sale",
  text: "Our spring sale is live! 20% off everything.",
  contact_list_ids: ["list_abc"]
)

# Preview cost + reachability before sending
preview = client.campaigns.preview(campaign.id)
puts "Recipients: #{preview.recipient_count}"
puts "Credits needed: #{preview.estimated_credits}"
puts "Enough credits? #{preview.enough_credits?}"

# Send now. The result is a Sendly::CampaignSendResult (a Sendly::Campaign)
# describing the batch the messages went out in: status is the batch's
# ("processing", "completed", "partial_failure" or "failed").
result = client.campaigns.send_campaign(campaign.id)
puts "Batch #{result.batch_id}: #{result.sent_count}/#{result.recipient_count} sent, " \
     "#{result.failed_count} failed, #{result.credits_used} credits"

# The campaign itself is "completed" once sent
puts client.campaigns.get(campaign.id).completed?

# Or, instead of sending now, schedule a draft for later
client.campaigns.schedule(campaign.id, scheduled_at: (Time.now.utc + 86_400).iso8601, timezone: "America/New_York")

# List, update, cancel, clone, delete
client.campaigns.list(status: "completed")[:campaigns].each { |c| puts "#{c.name}: #{c.status}" }
client.campaigns.update(campaign.id, name: "Spring Sale (v2)")
client.campaigns.cancel(campaign.id)
client.campaigns.clone(campaign.id)
client.campaigns.delete(campaign.id)

# Create / list / get. New templates start as drafts; publish to lock one for use.
template = client.templates.create(
  name: "Order shipped",
  text: "Hi {{name}}, order {{order_id}} has shipped!"
)
client.templates.list[:templates].each { |t| puts "#{t.name} — #{t.status}" }
t = client.templates.get(template.id)

# Update (drafts only) and publish
client.templates.update(template.id, text: "Hi {{name}}, your order is on the way!")
client.templates.publish(template.id)

# Copy a template into a new draft, then delete the original
copy = client.templates.clone(template.id, name: "Order shipped (v2)")
client.templates.delete(template.id)

# Generate a template with AI
generated = client.templates.generate(description: "A friendly appointment reminder")
puts generated.text
puts generated.variables.inspect

# List conversations (Enumerable)
conversations = client.conversations.list(status: "active")
conversations.each { |c| puts "#{c.phone_number}: #{c.last_message_text}" }

# Get one, optionally with its messages
convo = client.conversations.get("conv_abc", include_messages: true)

# Reply in a thread with text, media, or both (a reply with neither raises
# Sendly::ValidationError before anything is sent). Returns a Sendly::Message.
client.conversations.reply("conv_abc", text: "Thanks for reaching out!")
client.conversations.reply("conv_abc", media_urls: ["https://cdn.acme.example/menu.jpg"])

# Lifecycle + metadata
client.conversations.mark_read("conv_abc")
client.conversations.close("conv_abc")
client.conversations.reopen("conv_abc")
client.conversations.update("conv_abc", tags: ["priority"], metadata: { csat: 5 })

# Apply / remove labels
client.conversations.add_labels("conv_abc", label_ids: ["label_1"])
client.conversations.remove_label("conv_abc", label_id: "label_1")

# AI: conversation context + suggested replies
context = client.conversations.get_context("conv_abc", max_messages: 20)
puts context.token_estimate

replies = client.conversations.suggest_replies("conv_abc")
replies.each { |r| puts "[#{r.tone}] #{r.text}" }

# Auto-paginate every conversation
client.conversations.each(status: "active") { |c| puts c.id }

draft = client.drafts.create(
  conversation_id: "conv_abc",
  text: "Here's the info you asked for.",
  source: "agent"
)

client.drafts.list(conversation_id: "conv_abc", status: "pending").each { |d| puts d.text }
client.drafts.update(draft.id, text: "Here is the info you asked for.")

# Approve (sends the message) or reject with a reason
client.drafts.approve(draft.id)
client.drafts.reject(draft.id, reason: "Needs the discount code")

label = client.labels.create(name: "Urgent", color: "#ff0000", description: "Needs a fast reply")
client.labels.list.each { |l| puts l.name }
client.labels.delete(label.id)

rule = client.rules.create(
  name: "Auto-label opt-outs",
  conditions: { intent: "opt_out" },
  actions: { addLabels: ["label_1"] },
  priority: 1
)

client.rules.list.each { |r| puts "#{r.name} (priority #{r.priority})" }
client.rules.update(rule.id, priority: 2)
client.rules.delete(rule.id)

# Send a verification code
verification = client.verify.send(to: "+15125550123", app_name: "Acme")
puts verification.id

# Check the code the user entered
result = client.verify.check(verification.id, code: "123456")
puts result.verified?

# Resend, fetch, and list
client.verify.resend(verification.id)
client.verify.get(verification.id)
client.verify.list[:verifications].select { |v| v.status == "verified" }.each { |v| puts v.phone }

# Hosted verification session (returns a URL to send the user to)
session = client.verify.sessions.create(
  success_url: "https://acme.example/verified",
  brand_name: "Acme"
)
puts session.url
check = client.verify.sessions.validate(token: "session_token")
puts check.valid?

# From a file path
media = client.media.upload("flyer.jpg", content_type: "image/jpeg")
puts media.url

# ...then attach it to a send
client.messages.send(to: "+15125550123", text: "Check this out!", media_urls: [media.url])

# List supported countries and the number types available in each
client.numbers.list_countries[:countries].each do |country|
  puts "#{country.code} #{country.name}: #{country.number_types.join(', ')}"
end

# Find available numbers (monthly_cost is already customer-priced)
result = client.numbers.list_available(country: 'GB', type: 'mobile', contains: '777')
number = result[:numbers].first
puts "#{number.phone_number} — #{number.monthly_cost} #{number.currency}/mo"

# List numbers you already own
client.numbers.list[:numbers].each do |n|
  puts "#{n.phone_number} (#{n.status})"
end

# Buy a number
purchase = client.numbers.buy(
  phone_number: number.phone_number,
  country_code: number.country,
  phone_number_type: number.number_type,
  monthly_cost: number.monthly_cost
)

case purchase.status
when 'provisioning'
  puts "Provisioning #{purchase.number.phone_number}"
when 'documents_required', 'payment_required'
  # The action carries TWO different identifiers, and they are not
  # interchangeable:
  #   action_code       - the short code you SHOW the user to type on the
  #                       hosted page. Display only.
  #   action_identifier - the 32-hex identifier you PASS BACK to buy.
  puts "Visit #{purchase.action_url} and enter code #{purchase.action_code}"
  # ...after the action completes, re-call buy with the same arguments plus:
  # client.numbers.buy(..., action_code: purchase.action_identifier)
end

# Get one number you own (includes is_default, which the list omits)
number = client.numbers.get('num_abc123')
puts "#{number.phone_number} — default sender: #{number.is_default}"
puts "voice: #{number.voice_enabled?} (#{number.voice_mode})"

# Update a number — make it the default sender (must be active),
# and/or cancel a scheduled release ("keep this number")
client.numbers.update('num_abc123', is_default: true)
client.numbers.update('num_abc123', pending_cancellation: false)

# Release a number. A live paid purchase is cancelled at the end of the paid
# period (scheduled?), everything else is released immediately.
result = client.numbers.release('num_abc123')
if result.scheduled?
  puts "Releases at #{result.scheduled_release_at}"
else
  puts "Released"
end

# 1. Register a brand for carrier review
brand = client.ten_dlc.create_brand(
  legal_name: 'Acme Holdings LLC',
  ein: '12-3456789',
  website: 'https://acme.example',
  email: 'ops@acme.example'
)

# Poll until the brand is verified (or failed, with failure_reasons)
refreshed = client.ten_dlc.get_brand(brand.id)
puts refreshed.status  # "pending" -> "verified"

# 2. Pre-check your use case, then create a campaign
check = client.ten_dlc.qualify(brand.id, 'MIXED')
if check.qualified?
  campaign = client.ten_dlc.create_campaign(
    brand_id: brand.id,
    use_case: 'MIXED',
    description: 'Order updates and support replies for Acme customers',
    message_flow: 'Customers opt in at checkout on acme.example',
    sample_messages: ['Your order #123 has shipped!'],
    opt_out_keywords: 'STOP'
  )

  # Poll until carriers approve
  approved = client.ten_dlc.get_campaign(campaign.id)
  puts approved.status            # "awaiting_review" -> "pending" -> "active"
  puts approved.throughput&.tier  # e.g. "Standard"

  # 3. Assign a number you own — it can send once the assignment is Active
  assignment = client.ten_dlc.assign_number(campaign.id, phone_number: '+15125550123')
  puts assignment.status  # "Under review" -> "Active"
end

# List everything
client.ten_dlc.list_brands[:brands].each { |b| puts "#{b.legal_name} — #{b.status}" }
client.ten_dlc.list_campaigns[:campaigns].each { |c| puts "#{c.use_case} — #{c.status}" }
client.ten_dlc.list_assignments[:assignments].each { |a| puts "#{a.phone_number} — #{a.status}" }

client.webhooks.create(
  url: "https://acme.example/webhooks/sendly",
  events: [
    Sendly::Webhooks::EVENT_SHORT_CODE_ACTION_REQUIRED, # something needs you
    Sendly::Webhooks::EVENT_SHORT_CODE_REJECTED,        # data.object[:reason]
    Sendly::Webhooks::EVENT_SHORT_CODE_FILED,           # filed with the carriers
    Sendly::Webhooks::EVENT_SHORT_CODE_LIVE             # data.object[:short_code]
  ]
)

case event.type
when Sendly::Webhooks::EVENT_SHORT_CODE_LIVE
  # data.object carries short_code_id, short_code and organization_id
  puts "#{event.data[:short_code]} is live"
when Sendly::Webhooks::EVENT_SHORT_CODE_ACTION_REQUIRED
  puts "waiting on you at stage #{event.data[:stage]}"
end

application = client.get("/short_codes/application")

# Validate before submitting — advisory only, nothing is written.
# verdict is "ready", "warnings" or "blocked".
preview = client.business_upgrade.preflight(
  business_name: "Acme Holdings LLC",
  brn: "12-3456789",
  brn_type: "EIN",                    # Sendly::BusinessUpgradeResource::BRN_TYPES
  brn_country: "US",
  entity_type: "PRIVATE_PROFIT"       # Sendly::BusinessUpgradeResource::ENTITY_TYPES
)
puts preview["verdict"]
preview["issues"].each { |i| puts "#{i['severity']} #{i['field']}: #{i['code']}" }

# Prefill from the caller's other verified workspaces
best = client.business_upgrade.best_prefill

# Submit, with the IRS letter attached (ein_doc_path OR ein_doc, not both)
client.business_upgrade.start("ws_abc",
  business_name: "Acme Holdings LLC",
  brn: "12-3456789",
  brn_type: "EIN",
  brn_country: "US",
  entity_type: "PRIVATE_PROFIT",
  ein_doc_path: "./CP-575.pdf")

client.business_upgrade.status("ws_abc")     # { "pending" => nil } when none
client.business_upgrade.resubmit("ws_abc", contact_email: "ops@acme.example")
client.business_upgrade.cancel("ws_abc")

# After approval, decide what happens to the old toll-free number
client.business_upgrade.set_disposition("ws_abc",
  disposition: "moved",                      # or "released"
  target_workspace_id: "ws_other")

# Shorten a URL (must be http/https)
link = client.links.create(url: "https://acme.example/spring-sale?utm_source=sms")
puts link.short_url        # => "https://sendly.live/l/Ab3xY7"
puts link.code             # => "Ab3xY7"
puts link.destination_url  # => "https://acme.example/spring-sale?utm_source=sms"

# List your links with click counts (limit 1-200, default 50)
listing = client.links.list(limit: 20)
puts listing.total
listing.each do |l|
  puts "#{l.short_url} -> #{l.destination_url} (#{l.click_count} clicks)"
  puts "  last click: #{l.last_country} #{l.last_clicked_at}"
  puts "  14-day spark: #{l.spark.inspect}"
end

# Disable (redirect returns 404) or re-enable a link
client.links.disable(link.code)
client.links.enable(link.code)

# Or set the state explicitly
status = client.links.update(link.code, disabled: true)
puts status.disabled?

# 1. Connect a number ($19 one-time; a human must open the connect URL)
signup = client.whatsapp.signup.create(phone_number: "+15125550123")
puts "Have your user open: #{signup.connect_url}"

# 2. Poll until active. After the Facebook step the signup is "registering"
# while WhatsApp activates the number. Activation usually takes a few minutes
# but can take hours. If it hasn't finished about 6 hours after the session
# began, the session fails with registration_timeout and the fee is refunded.
# If the connection fails, the $19 fee is refunded automatically; once a
# number has connected, a later disconnect gets nothing back.
status = client.whatsapp.signup.get(signup.id)
puts status.failure_reasons if status.failed?  # e.g. ["waba_mismatch"]

# List your connected senders
client.whatsapp.senders.list[:senders].each do |s|
  puts "#{s.phone_number} (#{s.display_name || 'no name yet'}) — #{s.status}"
end

# Read and update a sender's business profile (what recipients see when
# they open your details in WhatsApp)
profile = client.whatsapp.senders.get_profile("+15125550123")
puts profile.display_name
puts profile.about

client.whatsapp.senders.update_profile(
  "+15125550123",
  about: "Fresh roasted coffee, delivered.",               # max 139 chars
  description: "Small-batch roaster shipping nationwide.", # max 512 chars
  website: "https://acme.example"
)

# Profile photo: a JPEG or PNG of at most 5 MB, square, at least 192 px wide
client.whatsapp.senders.upload_profile_photo("+15125550123", "logo.png",
                                             content_type: "image/png", filename: "logo.png")
client.whatsapp.senders.delete_profile_photo("+15125550123")

# Ice breakers (tappable suggestions on a first chat) and "/" commands. Each
# list you pass replaces the stored one; [] clears it.
client.whatsapp.senders.update_conversational_components(
  "+15125550123",
  ice_breakers: ["Track my order", "Opening hours"],     # at most 4
  commands: [{ command: "menu", description: "See today's menu" }]  # at most 30
)
components = client.whatsapp.senders.get_conversational_components("+15125550123")
components.commands.each { |c| puts "/#{c.command}: #{c.description}" }

# WhatsApp calling: WhatsApp users calling the number ring like a phone call.
# Switch voice on for the number first. There is no API for placing WhatsApp
# calls.
settings = client.whatsapp.senders.set_calling("+15125550123", enabled: true)
puts settings.calling_enabled?

# Add another number to the account you already connected: no Facebook step.
# Meta sends the number a 6-digit code by text ("sms", the default) or call.
sender = client.whatsapp.senders.list[:senders].find(&:active?)
added = client.whatsapp.signup.create(
  phone_number: "+15125550124",
  business_account_id: sender.business_account_id,
  verification_method: "sms"
)
puts added.status  # "verifying"

# The code can be read back once Meta's text arrives on the number. Until a
# code has been submitted it is the newest code since the signup started, so
# after a resend it still shows the earlier code until the new one arrives.
# Once WhatsApp has checked a code, only a code that arrived after the last
# submission or resend is returned. A 502 whatsapp_verification_unavailable
# isn't counted, so the same unchecked code can come back, and submitting it
# again is safe.
code = client.whatsapp.signup.get(added.id).verification_code
client.whatsapp.signup.verify(added.id, code: code) if code
# Or ask for a new one (at most every 30 seconds)
client.whatsapp.signup.resend(added.id, verification_method: "voice")

# 3. Create a template (Meta reviews it, usually 24-48h)
template = client.whatsapp.templates.create(
  sender: "+15125550123",
  name: "order_shipped",
  language: "en_US",
  category: "UTILITY",
  header: "Order update",  # fixed text only: a header with {{n}} is refused
  body: "Hi {{1}}, your order {{2}} has shipped!",
  examples: { "1" => "Sam", "2" => "#4821" }
)
puts template.status  # "PENDING"

# List, edit-and-resubmit (the recovery path for rejections), or delete
client.whatsapp.templates.list[:templates].each { |t| puts "#{t.name} — #{t.status}" }
client.whatsapp.templates.update(template.id, body: "Hi {{1}}, order {{2}} is on its way!",
                                              examples: { "1" => "Sam", "2" => "#4821" })
client.whatsapp.templates.delete(template.id)

# 4. Send — free-form inside an open 24h window, template anytime. The window
# is exactly { open, expiresAt }: no window on record reads open false with
# expires_at nil; an expired one reads open false with its past expires_at.
window = client.whatsapp.window(from: "+15125550123", to: "+15555550100")
if window.open?
  client.messages.send(
    channel: "whatsapp",
    to: "+15555550100",
    from: "+15125550123",
    text: "Your table is ready!"
  )
else
  message = client.messages.send(
    channel: "whatsapp",
    to: "+15555550100",
    from: "+15125550123",
    template: {
      name: "order_shipped",
      language: "en_US",
      variables: { "1" => "Acme Inc", "2" => "#4821" }
    }
  )
  puts message.whatsapp.kind  # "template"
end

# Media with a caption (also window-bound; one attachment per message)
client.messages.send(
  channel: "whatsapp",
  to: "+15555550100",
  from: "+15125550123",
  text: "Here is your receipt",
  media_urls: ["https://acme.example/receipt.pdf"]
)

# Where is the registration at?
reg = client.rcs.registration.get
puts reg.stage  # "draft" until something is submitted

# Seed the brand from details Sendly already holds (your 10DLC brand or
# toll-free verification), then fill in the rest
dossier = client.rcs.dossier.get
brand = client.rcs.brands.create(**dossier.brand)  # dossier.source: "tendlc", "verification" or "none"
client.rcs.brands.update(brand.id,
  display_name: "Acme Coffee",
  legal_entity_type: "LIMITED_LIABILITY_COMPANY",
  contact: { first_name: "Sam", last_name: "Lee", email: "sam@acme.example",
             phone_number: "+15125550123" }
)

# Draft the agent. Media must be public https URLs.
agent = client.rcs.agents.create(
  brand_id: brand.id,
  display_name: "Acme Coffee",
  use_case: "MULTI_USE",
  basics: {
    description: "Order updates and offers from Acme Coffee",
    logo_url: "https://acme.example/rcs/logo.png",
    hero_url: "https://acme.example/rcs/hero.png",
    brand_color: "#5B3A29",
    privacy_policy_url: "https://acme.example/privacy",
    terms_and_conditions_url: "https://acme.example/terms",
    phone_number: { number: "+15125550123", label: "Support" }
  }
)

# Submit for Sendly's review. Pass your own key if you may retry: a replay
# returns the original response without submitting again.
agent = client.rcs.agents.submit(agent.id, idempotency_key: "rcs-submit-#{agent.id}")
puts agent.review_status  # "awaiting_review"

# Later: poll, and act on a review note
agent = client.rcs.agents.get(agent.id)
if agent.changes_requested?
  puts agent.review_note
  client.rcs.agents.update(agent.id, basics: { hero_url: "https://acme.example/rcs/hero-v2.png" })
end

# Once the agent is in testing, invite devices, describe the campaign,
# then request launch
client.rcs.agents.set_test_devices(agent.id, devices: [
  { phone_number: "+15125550123", label: "Sam's Pixel" }
])
client.rcs.agents.update(agent.id,
  campaign: {
    company_overview: "Specialty coffee roaster with three cafes in Austin",
    agent_overview: "Order updates, pickup alerts and support replies",
    interactions: [{ interaction_type: "TRANSACTIONAL_UPDATES",
                     description: "Order and pickup status" }],
    message_examples: ["Your order #4821 has shipped!",
                       "Your latte is ready for pickup at 5th St",
                       "Reply HELP for support or STOP to opt out"],
    consent_settings: {
      opt_in_methods: [{ method_type: "WEBSITE", description: "Checkbox at checkout" }],
      call_to_action: "Get order updates by RCS",
      call_to_action_url: "https://acme.example/updates",
      double_opt_in: false,
      help_response: "Acme Coffee: reply STOP to opt out, or email help@acme.example",
      opt_out_response: "You're opted out of Acme Coffee updates."
    }
  }
)
client.rcs.agents.request_launch(agent.id, test_url: "https://acme.example/rcs-test")

# Discover your RCS agents ("testing" reaches invited test devices only;
# "approved" reaches everyone). Pass agent_id on sends and capability
# checks when your workspace has more than one agent.
client.rcs.agents.list[:agents].each do |a|
  puts "#{a.name} — #{a.status}#{a.sendable? ? ' (sendable)' : ''}"
end

# Pre-flight: can this recipient receive RCS?
capability = client.rcs.capability(to: "+15125550123")
puts capability.capable? ? "RCS" : "would fall back to SMS"

# Text with suggested replies and actions. Nested suggestion and card
# hashes are passed through verbatim, so they use the camelCase keys the
# API expects.
message = client.messages.send(
  channel: "rcs",
  to: "+15125550123",
  text: "Your order has shipped! Want live updates?",
  suggestions: [
    { reply: { text: "Yes, notify me", postbackData: "notify_yes" } },
    { action: { text: "Track order", postbackData: "track",
                url: "https://acme.example/orders/4821" } }
  ]
)

# The response discloses which channel delivered
puts message.channel # "rcs", or "sms" when it fell back
if message.fell_back?
  # Delivered as plain SMS (billed as SMS). Suggestions have no SMS form
  # and were dropped — message.rcs.suggestions_dropped is true.
else
  puts message.rcs.kind       # "text" or "card"
  puts message.rcs.agent_name # the brand name recipients see
end

# Rich card (RCS-capable recipients only — cards have no SMS form)
client.messages.send(
  channel: "rcs",
  to: "+15125550123",
  card: {
    title: "Spring collection",
    description: "New arrivals are in - take a look.",
    mediaUrl: "https://acme.example/spring.jpg", # public JPEG, PNG, or GIF
    orientation: "vertical",                    # or "horizontal"
    suggestions: [
      { action: { text: "Shop now", postbackData: "shop",
                  url: "https://acme.example/spring" } }
    ]
  }
)

# Opt out of the SMS fallback — the send raises Sendly::ValidationError
# (HTTP 422 rcs_not_supported_for_recipient) when the recipient can't
# receive RCS
client.messages.send(
  channel: "rcs",
  to: "+15125550123",
  text: "RCS or nothing",
  fallback_to_sms: false
)

from = client.numbers.list[:numbers].find(&:voice_enabled?)&.phone_number

# Place a call. Returns at once with the call ringing; the agent greets the
# callee when they answer and uses `context` for this call only.
call = client.calls.create(
  to: "+15125550123",
  agent_id: "3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b",
  from: "+15555550100",                # optional when you have one voice number
  context: "Confirm the 3pm appointment on Tuesday.",
  metadata: { "crmId" => "lead_8812" } # up to 20 string pairs, echoed everywhere
)
puts call.id
puts call.status        # "ringing"
puts call.handled_by    # "agent"

# Follow it. Agent-handled calls include a transcript once fetched by id.
call = client.calls.get(call.id)
puts call.status        # "ringing" -> "active" -> "completed" (or no_answer, busy, ...)
puts call.hangup_class  # why it ended, e.g. "agent_agent_hangup"
puts call.credits_charged
call.transcript&.each { |line| puts "#{line.speaker}: #{line.text}" }

# List (newest first; limit 1-100, default 50)
page = client.calls.list(status: "completed", direction: "outbound", agent_id: call.agent_id, limit: 20)
page.each { |c| puts "#{c.to} #{c.duration_secs}s #{c.credits_charged} credits" }
puts page.total
puts page.has_more?

# End a call. Ringing -> "cancelled", active -> "completed"; a call that
# has already ended comes back unchanged.
client.calls.hangup(call.id)

# Recording. The URL is signed and valid for five minutes; it is nil until
# the recording is ready. Ogg/Opus; agent calls are dual channel, with the
# agent on the left channel and the other party on the right.
rec = client.calls.recording(call.id)
if rec.ready?
  File.binwrite("#{call.id}.ogg", Net::HTTP.get(URI(rec.url)))
end

# Numbers. Pass the number's id or its E.164 phone number.
client.voice.numbers.list.each do |n|
  puts "#{n.phone_number} #{n.voice_mode} #{n.emergency_address&.status || 'no emergency address'}"
end
number = client.voice.numbers.get("+15125550123")
puts number.rate_per_minute.agent   # credits a minute when an agent answers

# A US or Canadian number needs an emergency address before it can place
# calls. The first registration adds $1.50 a month to the number;
# registering again replaces the address without a second charge.
number = client.voice.numbers.register_emergency_address(
  "+15125550123",
  street: "500 Example Ave",
  unit: "Suite 2",
  city: "Austin",
  state: "TX",
  zip: "78701"                      # country: defaults to "US"
)
puts number.emergency_address.status

# Voices and agents. An agent answers real callers on any number pointed at it.
client.voice.voices.list.each { |v| puts "#{v.id}: #{v.label}" }

agent = client.voice.agents.create(
  name: "Front desk",
  voice: "ashley",
  greeting: "Thanks for calling Acme, how can I help?",
  instructions: "Answer questions about opening hours and take a message for anything else.",
  tools: { send_sms: true }         # snake_case or camelCase keys
)
puts agent.can_send_sms?            # true once it holds its scoped sending key
client.voice.agents.update(agent.id, greeting: "Thanks for calling Acme. How can I help today?")
client.voice.agents.list.each { |a| puts "#{a.name}: #{a.calls_handled} calls" }

# Switching voice on changes how real calls to the number are answered.
client.voice.numbers.update("+15125550123", voice_enabled: true, voice_mode: "agent", agent_id: agent.id)
client.voice.numbers.update("+15125550123", voice_mode: "ring_dashboard") # ring the team instead
client.voice.numbers.update("+15125550123", voice_enabled: false)         # switch voice off

# An agent that answers a number can't be deleted until the number is moved.
begin
  client.voice.agents.delete(agent.id)
rescue Sendly::APIError => e
  raise unless e.response_body&.dig("error") == "agent_in_use"

  puts "Still answers #{e.response_body['numbers'].join(', ')}"
end

begin
  message = client.messages.send(
    to: "+15125550123",
    text: "Hello!"
  )
rescue Sendly::AuthenticationError => e
  puts "Invalid API key"
rescue Sendly::RateLimitError => e
  if e.response_body&.dig("error") == "too_many_failed_key_attempts"
    # Repeated wrong API keys from this address locked it out for up to
    # 5 minutes. Fix the key; do not retry until the lockout ends.
    puts "Locked out for #{e.retry_after}s: check the API key"
  else
    puts "Rate limited (#{e.response_body&.dig('error')}), retry after #{e.retry_after} seconds"
  end
rescue Sendly::InsufficientCreditsError => e
  puts "Add more credits to your account"
rescue Sendly::ValidationError => e
  puts "Invalid request: #{e.message}"
rescue Sendly::NotFoundError => e
  puts "Resource not found"
rescue Sendly::NetworkError => e
  puts "Network error: #{e.message}"
rescue Sendly::Error => e
  puts "Error: #{e.message} (#{e.response_body&.dig('error') || e.code})"
end

message.id           # Unique identifier
message.to           # Recipient phone number
message.from         # Sender ID or number (the default sender when you omit from:; "SENDLY-TEST" when simulated)
message.text         # Message content
message.status       # see Message Status below
message.direction    # "outbound" or "inbound"
message.segments     # Number of SMS segments
message.credits_used # Credits consumed
message.is_sandbox   # true for a simulated message (read it via messages.get or list; a send response leaves it false)
message.sender_type  # "number_pool", "alphanumeric" or "explicit" (live sends only)
message.created_at   # Creation time (Time)
message.delivered_at # Delivery time (Time, if delivered)
message.error        # Error message (if failed)
message.error_code   # Error code (if failed)
message.retry_count  # Delivery retry attempts
message.metadata     # The metadata Hash you attached
message.media_urls   # Attachments of an MMS; [] when there are none
message.message_format # "sms", "mms", "rcs" or "whatsapp" ("sms" when the API does not say)
message.ai_metadata  # AI classification, on inbound messages
message.warning      # Warning about the send, when the API sent one
message.sender_note  # Note about sender behaviour, when the API sent one

# Helper methods
message.delivered?   # => true/false
message.failed?      # => true/false
message.pending?     # => true/false
message.to_h         # => Hash of the above

client = Sendly::Client.new(api_key: "sk_live_v1_your_master_key")

result = client.enterprise.provision(
  name: "Acme Insurance - Austin",
  source_workspace_id: "ws_verified",
  credit_amount: 5000,
  credit_source_workspace_id: "SOURCE_WORKSPACE_ID",
  key_name: "Production",
  key_type: "live",
  generate_opt_in_page: true
)

puts result["workspace"]["id"]
puts result["key"]["key"]

ws = client.enterprise.workspaces.create(name: "Acme Insurance")
list = client.enterprise.workspaces.list
detail = client.enterprise.workspaces.get("ws_xxx")
client.enterprise.workspaces.delete("ws_xxx")

client.enterprise.workspaces.transfer_credits("ws_dest",
  source_workspace_id: "ws_source", amount: 5000)

# type: is "test" (the default) or "live"; scopes: defaults to every scope.
# A name is required: a missing or empty one raises ArgumentError.
key = client.enterprise.workspaces.create_key("ws_xxx",
  name: "Production", type: "live", scopes: ["sms:send", "sms:read"])
puts key["key"]      # shown only once
puts key["scopes"].inspect

client.enterprise.workspaces.revoke_key("ws_xxx", "key_abc")

client.enterprise.webhooks.set(url: "https://hooks.acme.example/enterprise")
client.enterprise.webhooks.test
client.enterprise.webhooks.rotate_secret

overview = client.enterprise.analytics.overview
messages = client.enterprise.analytics.messages(period: "30d")
delivery = client.enterprise.analytics.delivery
credits  = client.enterprise.analytics.credits(period: "30d")

# Verification, per workspace. A first submission needs business_name, website,
# address, contact, use_case, use_case_summary, sample_messages and
# opt_in_workflow. A resubmit after a rejection may send only the top-level
# fields that change, but an address or contact Hash replaces the stored one
# whole, so send every key of it.
client.enterprise.workspaces.submit_verification("ws_xxx", **verification_fields)
client.enterprise.workspaces.resubmit_verification("ws_xxx",
  contact: { firstName: "Sam", lastName: "Rivera", email: "new@acme.example", phone: "+15555550100" })
# Share the source workspace's verification and sending number (nothing is
# bought), or copy only its business details and buy the workspace its own
# toll-free number; the response then has "newNumber" => true.
client.enterprise.workspaces.inherit_verification("ws_xxx", source_workspace_id: "ws_verified")
client.enterprise.workspaces.inherit_verification("ws_other", source_workspace_id: "ws_verified",
                                                              purchase_new_number: true)
client.enterprise.workspaces.get_verification("ws_xxx")
client.enterprise.upload_verification_document("./CP-575.pdf", workspace_id: "ws_xxx")

# Hosted opt-in pages, and a generated business page
client.enterprise.workspaces.list_opt_in_pages("ws_xxx")
client.enterprise.workspaces.create_opt_in_page("ws_xxx", business_name: "Acme LLC")
client.enterprise.workspaces.update_opt_in_page("ws_xxx", "page_x", header_color: "#5B3A29")
client.enterprise.workspaces.delete_opt_in_page("ws_xxx", "page_x")
client.enterprise.workspaces.set_custom_domain("ws_xxx", "page_x", domain: "sms.acme.example")
client.enterprise.generate_business_page(business_name: "Acme LLC")

# Members: invite into a workspace, list and cancel invitations
client.enterprise.workspaces.send_invitation("ws_xxx", email: "sam@acme.example", role: "member")
client.enterprise.workspaces.list_invitations("ws_xxx")
client.enterprise.workspaces.cancel_invitation("ws_xxx", "inv_x")

# Suspend / resume, quotas, per-workspace webhooks, bulk provisioning
client.enterprise.workspaces.suspend("ws_xxx", reason: "non-payment")
client.enterprise.workspaces.resume("ws_xxx")
client.enterprise.workspaces.get_quota("ws_xxx")
client.enterprise.workspaces.set_quota("ws_xxx", monthly_message_quota: 50_000)
client.enterprise.workspaces.set_webhook("ws_xxx", url: "https://yourapp.example/hooks")
client.enterprise.workspaces.list_webhooks("ws_xxx")
client.enterprise.workspaces.test_webhook("ws_xxx")
client.enterprise.workspaces.delete_webhooks("ws_xxx", webhook_id: "whk_xxx")
client.enterprise.workspaces.provision_bulk([{ name: "Acme Austin" }])  # max 100
client.enterprise.workspaces.get_credits("ws_xxx")
client.enterprise.workspaces.list_keys("ws_xxx")

# Enterprise-level account, credits and billing
client.enterprise.get_account
client.enterprise.credits.get
client.enterprise.credits.deposit(amount: 100_000, description: "Q4 top-up")
client.enterprise.settings.get_auto_top_up
client.enterprise.settings.update_auto_top_up(enabled: true, threshold: 1000, amount: 10_000)
client.enterprise.billing.get_breakdown(period: "30d")