phusion / frontapp

Ruby client to work with Frontapp API

Frontapp

Ruby client to work with Frontapp API (https://dev.frontapp.com)

Installation

gem install frontapp

Usage

The auth_token can be obtained from Frontapp, in Settings -> API & Integrations -> API

Create a Frontapp client

require 'frontapp'
client = Frontapp::Client.new(auth_token: 'token')

Optionally, set a custom user agent to identify your integration

client = Frontapp::Client.new(auth_token: 'token', user_agent: 'Eye-Phone Integration ([email protected]')

Attachments

# Download a file attachment
attachment_file = client.download_attachment("fil_55c8c149")

Channels

# Get all channels
channels = client.channels

# Get a specific channel
channel = client.get_channel("cha_55c8c149")

# Update the webhook url of a custom channel
client.update_channel!("cha_55c8c149", { settings: { webhook_url: "my-uri" } })

# Create custom channel
channel = client.create_channel!("inb_55c8c149",  { settings: { webhook_url: "my-uri" } })

# Get the inbox for a channel
inbox = client.get_channel_inbox("cha_55c8c149")

Comments

# Create a new comment in a conversation
comment = client.create_comment!("cnv_55c8c149", { author_id: "[email protected]", body: "text" })

# Get all comments for a conversation
comments = client.get_conversation_comments("cnv_55c8c149")

# Get a specific comment
comment = client.get_comment("com_55c8c149")

# Get all mentions in a comment
mentions = client.get_comment_mentions("com_55c8c149")

Contact Groups

# Get all contact groups
group = client.contact_groups

# Create a new contact group
group = client.create_contact_group!({ name: "Name" })

# Delete a contact group
client.delete_contact_group!("grp_55c8c149")

# Get all contacts in a group
contacts = client.get_contact_group_contacts("grp_55c8c149")

# Add contacts to a group
client.add_contacts_to_contact_group!("grp_55c8c149", { contact_ids: ["[email protected]", "[email protected]"] })

Contacts

# Get all contacts
contacts = client.contacts

# Get a specific contact
contact = client.get_contact("ctc_55c8c149")

# Update a contact
client.update_contact!("ctc_55c8c149", {
  name: "Name",
  description: "Description",
  avatar_url: "http://example.com/avatar",
  is_spammer: false,
  links: ["http://example.com"],
  group_names: ["Customer"]
})

# Create a new contact
contact = client.create_contact!({
  name: "Name",
  description: "Description",
  avatar_url: "http://example.com/avatar",
  is_spammer: false,
  links: ["http://example.com"],
  group_names: ["Customer"],
  handles: [{
    "handle": "@calculon",
    "source": "twitter"
  }],
  custom_fields: {
    job_title: "Engineer"
  }
})

# Delete a contact
client.delete_contact!("ctc_55c8c149")

# Get all conversations for a contact
# Optionally include a filter for conversation statuses
conversations = client.get_contact_conversations("ctc_55c8c149", { q: { statuses: ["assigned", "unassigned"] } })

# Add a handle to a contact
client.add_contact_handle!("ctc_55c8c149", { handle: "@calculon", source: "twitter" })

# Delete a handle from a contact
client.delete_contact_handle!("ctc_55c8c149", { handle: "@calculon", source: "twitter" })

# Force delete a handle from a contact, required if it is the last handle
client.delete_contact_handle!("ctc_55c8c149", { handle: "@calculon", source: "twitter", force: true })

# Get all notes for a contact
notes = client.get_contact_notes("ctc_55c8c149")

# Create a new note for a contact
note = client.add_contact_note!("ctc_55c8c149", {
  author_id: "[email protected]",
  body: "Foobar"
})

Conversations

# Get all conversations
conversations = client.conversations

# Get a specific conversation
converstation = client.get_conversation("cnv_55c8c149")

# Update a conversation
client.update_conversation!("cnv_55c8c149", {
  assignee_id: "[email protected]",
  status: "archived",
  inbox_id: "inb_55c8c149",
  tags: ["time travel"]
})

# Get all inboxes a conversation is in
inboxes = client.get_conversation_inboxes("cnv_55c8c149")

# Get all teammates following a conversation
followers = client.get_conversation_followers("cnv_55c8c149")

# Get all events for a conversation
events = client.get_conversation_events("cnv_55c8c149")

# Get all messages for a conversation
messages = client.get_conversation_messages("cnv_55c8c149")

# Add conversation links (by link_id)
client.add_conversation_links!("cnv_55c8c149", {
  link_ids: ["top_3ii5d", "top_3ih5t"]
})

# Add conversation links (by link) (it creates the link if doesn't exist)
client.add_conversation_links!("cnv_55c8c149", {
  link_links: ["https://example.com"]
})

# Remove conversation links
client.remove_conversation_links!("cnv_55c8c149", {
  link_ids: ["top_3ii5d", "top_3ih5t"]
})

# Add conversation followers
client.add_conversation_followers!("cnv_55c8c149", {
  teammate_ids: ["tea_64ue9", "tea_638yp"]
})

# Remove conversation followers
client.remove_conversation_followers!("cnv_55c8c149", {
  teammate_ids: ["tea_64ue9", "tea_638yp"]
})

Events

# Get all events
events = client.events

# Get a specific event
event = client.get_event("evt_55c8c149")

Inboxes

# Get all inboxes
inboxes = client.inboxes

# Get a specific inbox
inbox = client.get_inbox("inb_55c8c149")

# Create a new inbox
inbox = client.create_inbox!({ name: "Support", teammate_ids: [] })

# Get all channels for an inbox
channels = client.get_inbox_channels("inb_55c8c149")

# Get all conversations in an inbox
# Optionally include a filter for conversation statuses
conversations = client.get_inbox_conversations("inb_55c8c149", { q: { statuses: ["assigned", "unassigned"] } })

# Get all teammates that have access
teammates = client.get_inbox_teammates("inb_55c8c149")

Messages

# Get a specific message
message = client.get_message("msg_55c8c149")

# Get raw email source for a specific message
message_source = client.get_message_source("msg_55c8c149")

# Send a new message to a channel
conversation_reference = client.send_message("cha_55c8c149", {
  author_id: "[email protected]",
  subject: "Good news everyone!",
  body: "Why is Zoidberg the only one still alone?",
  text: "Why is Zoidberg the only one still alone?",
  options: {
    tags: [],
    archive: true
  },
  to: [
    "[email protected]"
  ],
  cc: [],
  bcc: []
})

# Send a reply to a conversation
client.send_reply("cnv_55c8c149", {
  author_id: "[email protected]",
  subject: "Good news everyone!",
  body: "Why is Zoidberg the only one still alone?",
  text: "Why is Zoidberg the only one still alone?",
  options: {
    tags: [],
    archive: true
  },
  channel_id: "cha_55c8c149",
  to: [],
  cc: [],
  bcc: []
})

# Receive a custom message on a channel
conversation_reference = client.receive_custom_message("cha_55c8c149", {
  sender: {
    name: "hermes",
    handle: "hermes_123"
  },
  subject: "Question",
  body: "Didn't we used to be a delivery company?",
  metadata: {}
})

# Import a message into an inbox
conversation_reference = client.import_message("inb_55c8c149", {
  sender: {
    handle: "[email protected]"
  },
  to: [],
  cc: [],
  bcc: [],
  body: "",
  body_format: "html",
  external_id: "",
  created_at: 1453770984.123,
  tags: [],
  metadata: {
    is_inbound: true,
    is_archived: true,
    should_skip_rules: true
  }
})

Rules

# Get all rules
rules = client.rules

# Get a specific rule
rule = client.get_rule("rul_55c8c149")

Tags

# Get all tags
tags = client.tags

# Get specific tag
tag = client.get_tag("tag_55c8c149")

# Create tag
tag = client.create_tag!({name: "New tag name"})

# Delete tag
tag = client.delete_tag!("tag_55c8c149")

# Get all conversation for a tag
# Optionally include a filter for conversation statuses
conversations = client.get_tag_conversations("tag_55c8c149", { q: { statuses: ["assigned", "unassigned"] } })

Teams

# Get all teams
teams = client.teams

# Get a specific team
team = client.get_team("tim_55c8c149")

Teammates

# Get all teammates
teammates = client.teammates

# Get a teammate
teammate = client.get_teammate("[email protected]")

# Update a teammate
client.update_teammate!("[email protected]", {
  username: "bender",
  first_name: "Bender",
  last_name: "Rodriguez",
  is_admin: true,
  is_available: false
})

# Get all conversations for a teammate
conversations = client.get_teammate_conversations("[email protected]", { q: { statuses: ["assigned", "unassigned"] } })

# Get all inboxes for a teammate
inboxes = client.get_teammate_inboxes("[email protected]")

Topics

Topics is deprecated, please use Links instead!

# Get all conversations for a topic
# Optionally include a filter for conversation statuses
conversations = client.get_topic_conversations("top_55c8c149", { q: { statuses: ["assigned", "unassigned"] } })

Links

# Get all links
links = client.links

# Get a link
link = client.get_link("top_55c8c149")

# Create a new link
link = client.create_link!({
  name: "Nice link",
  external_url: "https://www.example.com/nice_link"
})

# Update a link
client.update_link!("top_55c8c149", { name: "Something new" })

# Get all conversations for a link
# Optionally include a filter for conversation statuses
conversations = client.get_link_conversations("top_55c8c149", { q: { statuses: ["assigned", "unassigned"] } })

### Exports
```ruby
# Get all exports
exports = client.exports

# Get a teammate
export = client.get_export("exp_55c8c149")

# Create a new export
contact = client.create_export!({
  inbox_id: "inb_55c8c149",
  start: 1428889003,
  end: 1428889008,
  timezone: "America/New_York",
  should_export_events: false
})

# Create a new export
contact = client.create_export_for_team!("tim_55c8c149", {
  inbox_id: "inb_55c8c149",
  start: 1428889003,
  end: 1428889008,
  timezone: "America/New_York",
  should_export_events: false
})

Contributors

Special thanks to:

• tatey
• techpeace
• jcrate
• langsharpe
• thechrisoshow
• feolea
• jefferal1995

frontapp's Issues

How to track errors?

Hey,

First off thanks for the library.

A question accoured, how can i track errors from the API? For example Unauhtorized error(so i can track whenever my token is correct/valid). I see it in object, but it's really not that accessable.

Thanks!

Empty body for attachments

When using the download_attachment method for an image, the response body does not contain the image content.

When I drop down and use HTTP directly, the response.ready_body invocation returns the binary data correctly but it doesn't seem to make it up into the frontapp gem's response.

Filtering Contacts?

Hey there!

Love what you have created.

Question: Is there a way to filter contacts? E.g. I want to find all contacts NOT in a group, or where a specific field is empty.

Cheers!

Delete Contact Handle isn't working

Whenever I try to use the delete_contact_handle! method, I get an error saying the handle can't be found for the specified contact, even though the handle is clearly assigned to that contact.

README should specify "author_id" takes the id not email address

Hi! Thanks for building this!

I just started using it, and wanted to flag that in the README author_id is given as an email address, but it appears — through use — that the value should be the teammate ID from the Front API, rather than the email address of that teammate.

Thus the example of:

comment = client.create_comment!("cnv_55c8c149", { author_id: "[email protected]", body: "text" })

should actually be something like

comment = client.create_comment!("cnv_55c8c149", { author_id: "trd_rfjh", body: "text" })

I'm new to Front's API so opening this issue rather than immediately jumping to a PR in case there's a foible I'm not familiar with here.

Thanks again!

Receive Message Error Handling + 502 Consistency

I know this is probably a product of the API as 502 probably means something flapping at the ingress but regardless the library spits out a weird exception as there is no error handling on status codes (Or there is and it assumes JSON) and it tries to decode an HTML response as JSON.

Version: 0.0.11
Rails: 6.1.7.3
Ruby: 2.7.7

Error Snippet:

[809: unexpected token at '<html> <head><title>502 Bad Gateway</title></head> <body> <center><h1>502 Bad Gateway</h1></center> </body> </html> '](REDACTED?queue=failed#)

Stack Trace

/usr/local/bundle/gems/json-2.5.1/lib/json/common.rb:216:in `parse'
/usr/local/bundle/gems/json-2.5.1/lib/json/common.rb:216:in `parse'
/usr/local/bundle/gems/frontapp-0.0.11/lib/frontapp/client.rb:103:in `create'
/usr/local/bundle/gems/frontapp-0.0.11/lib/frontapp/client/messages.rb:126:in `receive_custom_message

Request:

FrontClient.client.receive_custom_message(channel, {
                                                  sender:
                                                    {
                                                      name: 'REDACTED',
                                                      handle: 'REDACTED'
                                                    },
                                                  subject: 'REDACTED,
                                                  body: 'REDACTED
                                                })

I can go ahead and wrap a standard error around this but I figure I throw it your way for visibility on 502 and the potential for status unwrapping in code.