Go Bindings For Intercom
Go
Clone or download
Permalink
Failed to load latest commit information.
.github Add issue template Mar 18, 2016
fixtures Fetch the URL the User started a conversation on (#82) Oct 23, 2017
interfaces Pass status code to the unknown http error May 19, 2017
.gitignore int64 all the things Oct 12, 2015
.travis.yml add test for segment person type Mar 18, 2016
LICENSE license, readme Feb 27, 2015
README.md Webhook Notifications (#75) Oct 4, 2017
admin.go fetch conversations Jul 27, 2015
admin_api.go Include tag list when retrieving single conversations Jul 4, 2017
admin_api_test.go intercom go Feb 19, 2015
admin_test.go add messaging api Jul 27, 2015
bool.go intercom go Feb 19, 2015
company.go Add company scroll API Feb 15, 2017
company_api.go Add company scroll API Feb 15, 2017
company_api_test.go intercom go Feb 19, 2015
company_test.go Add company scroll stub Feb 16, 2017
contact.go Add support for Scroll API Feb 5, 2017
contact_api.go Add support for Scroll API Feb 5, 2017
contact_api_test.go Add phone attribute to users and contacts Jan 12, 2017
contact_test.go Add support for Scroll API Feb 5, 2017
conversation.go Fetch the URL the User started a conversation on (#82) Oct 23, 2017
conversation_api.go Use v2 imports everywhere Sep 28, 2015
conversation_api_test.go Fetch the URL the User started a conversation on (#82) Oct 23, 2017
conversation_test.go Add attachment support Sep 9, 2015
doc.go update docs refs Apr 25, 2017
event.go To add events for leads Jun 8, 2017
event_api.go Use v2 imports everywhere Sep 28, 2015
event_api_test.go int64 all the things Oct 12, 2015
event_test.go int64 all the things Oct 12, 2015
http_client_test.go add contact create and update Apr 29, 2015
intercom.go Use v2 imports everywhere Sep 28, 2015
intercom_error.go intercom go Feb 19, 2015
job.go add job api Sep 15, 2015
job_api.go Use v2 imports everywhere Sep 28, 2015
job_api_test.go add job api Sep 15, 2015
job_item.go add job api Sep 15, 2015
job_test.go add job api Sep 15, 2015
message.go fix message unmarshal Sep 21, 2016
message_api.go Use v2 imports everywhere Sep 28, 2015
message_api_test.go fix message unmarshal Sep 21, 2016
message_test.go add reply, open, assign Jul 28, 2015
notification.go Webhook Notifications (#75) Oct 4, 2017
notification_test.go Webhook Notifications (#75) Oct 4, 2017
page.go int64 all the things Oct 12, 2015
reply.go int64 all the things Oct 12, 2015
requestUserMapper.go Add phone attribute to users and contacts Jan 12, 2017
segment_api.go Use v2 imports everywhere Sep 28, 2015
segment_api_test.go remove unecessary segment person type Mar 18, 2016
segment_test.go intercom go Feb 19, 2015
segments.go remove unecessary segment person type Mar 18, 2016
tag.go intercom go Feb 19, 2015
tag_api.go Use v2 imports everywhere Sep 28, 2015
tag_api_test.go intercom go Feb 19, 2015
tag_test.go intercom go Feb 19, 2015
tagging.go intercom go Feb 19, 2015
user.go Added missing type to avatar object. (#81) Oct 4, 2017
user_api.go Add support for Scroll API Feb 5, 2017
user_api_test.go Add phone attribute to users and contacts Jan 12, 2017
user_test.go Add support for Scroll API Feb 5, 2017

README.md

Intercom-Go

Build Status

Thin client for the Intercom API.

Install

go get gopkg.in/intercom/intercom-go.v2

docker_image 1
Try out our Docker Image (Beta) to help you get started more quickly.
It should make it easier to get setup with the SDK and start interacting with the API.
(Note, this is in Beta and is for testing purposes only, it should not be used in production)

Usage

Getting a Client

import (
	intercom "gopkg.in/intercom/intercom-go.v2"
)
// You can use either an an OAuth or Access Token
ic := intercom.NewClient("access_token", "")

This client can then be used to make requests.

If you already have an access token you can find it here. If you want to create or learn more about access tokens then you can find more info here.

If you are building a third party application you can get your OAuth token by setting-up-oauth for Intercom. You can use the Goth library which is a simple OAuth package for Go web aplicaitons and supports Intercom to more easily implement Oauth.

Client Options

The client can be configured with different options by calls to ic.Option:

ic.Option(intercom.TraceHTTP(true)) // turn http tracing on
ic.Option(intercom.BaseURI("http://intercom.dev")) // change the base uri used, useful for testing
ic.Option(intercom.SetHTTPClient(myHTTPClient)) // set a new HTTP client, see below for more info

or combined:

ic.Option(intercom.TraceHTTP(true), intercom.BaseURI("http://intercom.dev"))

Users

Save

user := intercom.User{
	UserID: "27",
	Email: "test@example.com",
	Name: "InterGopher",
	SignedUpAt: int64(time.Now().Unix()),
	CustomAttributes: map[string]interface{}{"is_cool": true},
}
savedUser, err := ic.Users.Save(&user)
  • One of UserID, or Email is required.
  • SignedUpAt (optional), like all dates in the client, must be an integer(32) representing seconds since Unix Epoch.
Adding/Removing Companies

Adding a Company:

companyList := intercom.CompanyList{
	Companies: []intercom.Company{
		{ID: "5"},
	},
}
user := intercom.User{
	UserID: "27",
	Companies: &companyList,
}

Removing is similar, but adding a Remove: intercom.Bool(true) attribute to a company.

Find

user, err := ic.Users.FindByID("46adad3f09126dca")
user, err := ic.Users.FindByUserID("27")
user, err := ic.Users.FindByEmail("test@example.com")

List

userList, err := ic.Users.List(intercom.PageParams{Page: 2})
userList.Pages // page information
userList.Users // []User
userList, err := ic.Users.Scroll("")
scrollParam := userList.ScrollParam
userList, err := ic.Users.Scroll(scrollParam)
userList, err := ic.Users.ListBySegment("segmentID123", intercom.PageParams{})
userList, err := ic.Users.ListByTag("42", intercom.PageParams{})

Delete

user, err := ic.Users.Delete("46adad3f09126dca")

Contacts

Find

contact, err := ic.Contacts.FindByID("46adad3f09126dca")
contact, err := ic.Contacts.FindByUserID("27")

List

contactList, err := ic.Contacts.List(intercom.PageParams{Page: 2})
contactList.Pages // page information
contactList.Contacts // []Contact
contactList, err := ic.Contacts.Scroll("")
scrollParam = contactList.ScrollParam
contactList, err := ic.Contacts.Scroll(scrollParam)
contactList, err := ic.Contacts.ListByEmail("test@example.com", intercom.PageParams{})

Create

contact := intercom.Contact{
	Email: "test@example.com",
	Name: "SomeContact",
	CustomAttributes: map[string]interface{}{"is_cool": true},
}
savedContact, err := ic.Contacts.Create(&contact)
  • No identifier is required.
  • Set values for UserID will be ignored (consider creating Users instead)

Update

contact := intercom.Contact{
	UserID: "abc-13d-3",
	Name: "SomeContact",
	CustomAttributes: map[string]interface{}{"is_cool": true},
}
savedContact, err := ic.Contacts.Update(&contact)
  • ID or UserID is required.
  • Will not create new contacts.

Convert

Used to convert a Contact into a User

contact := intercom.Contact{
	UserID: "abc-13d-3",
}
user := intercom.User{
	Email: "myuser@signedup.com",
}
savedUser, err := ic.Contacts.Convert(&contact, &user)
  • If the User does not already exist in Intercom, the Contact will be uplifted to a User.
  • If the User does exist, the Contact will be merged into it and the User returned.

Companies

Save

company := intercom.Company{
	CompanyID: "27",
	Name: "My Co",
	CustomAttributes: map[string]interface{}{"is_cool": true},
	Plan: &intercom.Plan{Name: "MyPlan"},
}
savedCompany, err := ic.Companies.Save(&company)
  • CompanyID is required.

Find

company, err := ic.Companies.FindByID("46adad3f09126dca")
company, err := ic.Companies.FindByCompanyID("27")
company, err := ic.Companies.FindByName("My Co")

List

companyList, err := ic.Companies.List(intercom.PageParams{Page: 2})
companyList.Pages // page information
companyList.Companies // []Companies
companyList, err := ic.Companies.ListBySegment("segmentID123", intercom.PageParams{})
companyList, err := ic.Companies.ListByTag("42", intercom.PageParams{})

Events

Save

event := intercom.Event{
	UserID: "27",
	EventName: "bought_item",
	CreatedAt: int64(time.Now().Unix()),
	Metadata: map[string]interface{}{"item_name": "PocketWatch"},
}
err := ic.Events.Save(&event)
  • One of UserID, ID, or Email is required (With leads you need to use ID).
  • EventName is required.
  • CreatedAt is optional, must be an integer representing seconds since Unix Epoch. Will be set to now unless given.
  • Metadata is optional, and can be constructed using the helper as above, or as a passed map[string]interface{}.

Admins

List

adminList, err := ic.Admins.List()
admins := adminList.Admins

Tags

List

tagList, err := ic.Tags.List()
tags := tagList.Tags

Save

tag := intercom.Tag{Name: "GoTag"}
savedTag, err := ic.Tags.Save(&tag)

Name is required. Passing an ID will attempt to update the tag with that ID.

Delete

err := ic.Tags.Delete("6")

Tagging Users/Companies

taggingList := intercom.TaggingList{Name: "GoTag", Users: []intercom.Tagging{{UserID: "27"}}}
savedTag, err := ic.Tags.Tag(&taggingList)

A Tagging can identify a User or Company, and can be set to Untag:

taggingList := intercom.TaggingList{Name: "GoTag", Users: []intercom.Tagging{{UserID: "27", Untag: intercom.Bool(true)}}}
savedTag, err := ic.Tags.Tag(&taggingList)

Segments

List

segmentList := ic.Segments.List()
segments, err := segmentList.Segments

Find

segment, err := ic.Segments.Find("abc312daf2397")

Messages

New Admin to User/Contact Email

msg := intercom.NewEmailMessage(intercom.PERSONAL_TEMPLATE, intercom.Admin{ID: "1234"}, intercom.User{Email: "test@example.com"}, "subject", "body")
savedMessage, err := ic.Messages.Save(&msg)

Can use intercom.PLAIN_TEMPLATE too, or replace the intercom.User with an intercom.Contact.

New Admin to User/Contact InApp

msg := intercom.NewInAppMessage(intercom.Admin{ID: "1234"}, intercom.Contact{Email: "test@example.com"}, "body")
savedMessage, err := ic.Messages.Save(&msg)

New User Message

msg := intercom.NewUserMessage(intercom.User{Email: "test@example.com"}, "body")
savedMessage, err := ic.Messages.Save(&msg)

Conversations

Find Conversation

convo, err := intercom.Conversations.Find("1234")

List Conversations

All

convoList, err := intercom.Conversations.ListAll(intercom.PageParams{})

By User

Showing all for user:

convoList, err := intercom.Conversations.ListByUser(&user, intercom.SHOW_ALL, intercom.PageParams{})

Showing just Unread for user:

convoList, err := intercom.Conversations.ListByUser(&user, intercom.SHOW_UNREAD, intercom.PageParams{})

By Admin

Showing all for admin:

convoList, err := intercom.Conversations.ListByAdmin(&admin, intercom.SHOW_ALL, intercom.PageParams{})

Showing just Open for admin:

convoList, err := intercom.Conversations.ListByAdmin(&admin, intercom.SHOW_OPEN, intercom.PageParams{})

Showing just Closed for admin:

convoList, err := intercom.Conversations.ListByAdmin(&admin, intercom.SHOW_CLOSED, intercom.PageParams{})

Reply

User reply:

convo, err := intercom.Conversations.Reply("1234", &user, intercom.CONVERSATION_COMMENT, "my message")

User reply with attachment:

convo, err := intercom.Conversations.ReplyWithAttachmentURLs("1234", &user, intercom.CONVERSATION_COMMENT, "my message", string[]{"http://www.example.com/attachment.jpg"})

User reply that opens:

convo, err := intercom.Conversations.Reply("1234", &user, intercom.CONVERSATION_OPEN, "my message")

Admin reply:

convo, err := intercom.Conversations.Reply("1234", &admin, intercom.CONVERSATION_COMMENT, "my message")

Admin note:

convo, err := intercom.Conversations.Reply("1234", &admin, intercom.CONVERSATION_NOTE, "my message to just admins")

Open and Close

Open:

convo, err := intercom.Conversations.Open("1234", &openerAdmin)

Close:

convo, err := intercom.Conversations.Close("1234", &closerAdmin)

Assign

convo, err := intercom.Conversations.Assign("1234", &assignerAdmin, &assigneeAdmin)

Webhooks

Notifications

If you have received a JSON webhook notification, you may want to convert it into real Intercom object. A Notification can be created from any io.Reader, typically a http request:

var r io.Reader
notif, err := intercom.NewNotification(r)

The returned Notification will contain exactly 1 of the Company, Conversation, Event, Tag or User fields populated. It may only contain partial objects (such as a single conversation part) depending on what is provided by the webhook.

Errors

Errors may be returned from some calls. Errors returned from the API will implement intercom.IntercomError and can be checked:

_, err := ic.Users.FindByEmail("doesnotexist@intercom.io")
if herr, ok := err.(intercom.IntercomError); ok && herr.GetCode() == "not_found" {
	fmt.Print(herr)
}

HTTP Client

The HTTP Client used by this package can be swapped out for one of your choosing, with your own configuration, it just needs to implement the HTTPClient interface:

type HTTPClient interface {
	Get(string, interface{}) ([]byte, error)
	Post(string, interface{}) ([]byte, error)
	Patch(string, interface{}) ([]byte, error)
	Delete(string, interface{}) ([]byte, error)
}

It'll probably need to work with appId, apiKey and baseURI values. See the provided client for an example. Then create an Intercom Client and inject the HTTPClient:

ic := intercom.Client{}
ic.Option(intercom.SetHTTPClient(myHTTPClient))
// ready to go!

On Bools

Due to the way Go represents the zero value for a bool, it's necessary to pass pointers to bool instead in some places.

The helper intercom.Bool(true) creates these for you.

Pull Requests

  • Add tests! Your patch won't be accepted if it doesn't have tests.

  • Document any change in behaviour. Make sure the README and any other relevant documentation are kept up-to-date.

  • Create topic branches. Don't ask us to pull from your master branch.

  • One pull request per feature. If you want to do more than one thing, send multiple pull requests.

  • Send coherent history. Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please squash them before sending them to us.