gorgias-ruby

A professional-grade Ruby client for the Gorgias REST API.

Installation

Add to your Gemfile:

gem "gorgias-ruby"

Or install directly:

gem install gorgias-ruby

Configuration

Global (recommended for Rails apps)

Gorgias.configure do |config|
  config.domain   = "mycompany"          # your Gorgias subdomain
  config.username = "me@mycompany.com"   # agent email
  config.api_key  = ENV["GORGIAS_API_KEY"]
end

client = Gorgias.new   # uses global config

Per-client

client = Gorgias::Client.new(
  domain:   "mycompany",
  username: "me@mycompany.com",
  api_key:  ENV["GORGIAS_API_KEY"]
)

Optional settings

Gorgias.configure do |config|
  config.timeout      = 30   # read timeout in seconds (default: 30)
  config.open_timeout = 10   # connection timeout in seconds (default: 10)
  config.logger       = Logger.new($stdout)
end

Usage

All methods return Gorgias::Object instances (or arrays of them) that support both method-style and hash-style attribute access.

Account

account = client.account.retrieve
account.domain        # => "mycompany"
account.status.status # => "active"

Tickets

tickets = client.tickets.list(status: "open", limit: 20)
ticket  = client.tickets.retrieve(123)
ticket.subject  # => "My order is late"

client.tickets.create(
  subject:  "Delivery issue",
  channel:  "email",
  customer: { email: "john@example.com" },
  messages: [{ body_text: "Hi, my package hasn't arrived.", from_agent: false }]
)

client.tickets.update(123, status: "closed")
client.tickets.close(123)
client.tickets.mark_as_spam(123)
client.tickets.delete(123)

Ticket Messages

messages = client.ticket_messages.list(123)
message  = client.ticket_messages.retrieve(123, 456)

client.ticket_messages.create(123, body_text: "Thanks!", from_agent: true, channel: "email")
client.ticket_messages.update(123, 456, body_text: "Updated reply")
client.ticket_messages.delete(123, 456)

Customers

customers = client.customers.list(email: "john@example.com")
customer  = client.customers.retrieve(3924)

client.customers.create(name: "John Smith", email: "john@example.com")
client.customers.update(3924, name: "John Doe")
client.customers.delete(3924)
client.customers.delete_many([3924, 3925])

Users (Agents)

users = client.users.list
client.users.create(name: "Alice", email: "alice@mycompany.com", role: "agent")
client.users.update(7, name: "Alice B.")
client.users.delete(7)

Tags

client.tags.list
client.tags.create(name: "billing")
client.tags.merge(3, target_id: 4)
client.tags.delete(3)

Events

events = client.events.list(limit: 50)
event  = client.events.retrieve(789)
event.event_type  # => "ticket-created"

Search

client.search.tickets(query: "refund order")
client.search.customers(query: "john smith")
client.search.ticket_messages(query: "damaged")

Statistics

opts = { start_datetime: "2024-01-01T00:00:00Z", end_datetime: "2024-12-31T23:59:59Z" }

client.statistics.tickets(**opts)
client.statistics.customers(**opts)
client.statistics.customer_satisfaction(**opts)

Views

client.views.list
client.views.export(10)
client.views.create(name: "Open VIP tickets", type: "ticket")

Macros

client.macros.list
client.macros.create(name: "Refund approved", actions: [{ type: "assign-tag", value: "refunded" }])

Rules

client.rules.list
rule = client.rules.retrieve(5)
client.rules.create(name: "Auto-tag VIP", conditions: [], actions: [])
client.rules.update(5, name: "Auto-tag VIP (updated)")
client.rules.delete(5)

Integrations / Jobs / Satisfaction Surveys / Widgets

client.integrations.list
client.jobs.cancel(8)
client.satisfaction_surveys.accept(20, score: 5, body_text: "Great service!")
client.widgets.list

File Uploads

files = client.files.upload(
  "receipt.png" => File.open("/path/to/receipt.png", "rb"),
  "invoice.pdf" => File.open("/path/to/invoice.pdf", "rb")
)
files.first.url  # => "https://gorgias.io/attachments/receipt.png"

Response objects

ticket = client.tickets.retrieve(1)

ticket.id              # method access
ticket[:id]            # hash-style access
ticket.customer        # => #<Gorgias::Object ...>  (nested)
ticket.customer.email  # => "john@example.com"
ticket.tags            # => [#<Gorgias::Object ...>, ...]
ticket.to_h            # plain Hash

Error handling

begin
  client.tickets.retrieve(999)
rescue Gorgias::NotFoundError => e
  e.http_status   # => 404
rescue Gorgias::RateLimitError => e
  e.retry_after   # seconds until rate-limit resets
rescue Gorgias::UnprocessableEntityError => e
  e.errors        # => [{ "field" => "subject", ... }]
rescue Gorgias::AuthenticationError
  # bad credentials
rescue Gorgias::APIError => e
  # catch-all
end

Error hierarchy

Gorgias::Error
├── Gorgias::ConfigurationError
└── Gorgias::APIError
    ├── Gorgias::BadRequestError          (400)
    ├── Gorgias::AuthenticationError      (401)
    ├── Gorgias::AuthorizationError       (403)
    ├── Gorgias::NotFoundError            (404)
    ├── Gorgias::ConflictError            (409)
    ├── Gorgias::UnprocessableEntityError (422)
    ├── Gorgias::RateLimitError           (429)
    └── Gorgias::ServerError              (5xx)

Development

bundle install
bundle exec rspec

License

MIT