Intercom-Go

Thin client for the Intercom API.

Currently in beta, though breaking API changes are not expected.

Install

go get github.com/intercom/intercom-go

Usage

Getting a Client

The first step to using Intercom's Go client is to create a client object, using your App ID and Api Key from your settings.

import (
	"github.com/intercom/intercom-go"
)

ic := intercom.NewClient("appID", "apiKey")

This client can then be used to make requests.

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: "[email protected]",
	Name: "InterGopher",
	SignedUpAt: int32(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{
		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("[email protected]")

List

userList, err := ic.Users.List(intercom.PageParams{Page: 2})
userList.Pages // page information
userList.Users // []User

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.ListByEmail("[email protected]", intercom.PageParams{})

Create

contact := intercom.Contact{
	Email: "[email protected]",
	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: "[email protected]",
}
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: int32(time.Now().Unix()),
	Metadata: map[string]interface{}{"item_name": "PocketWatch"},
}
err := ic.Events.Save(&event)

• One of UserID, or Email is required.
• 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{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{intercom.Tagging{UserID: "27", Untag: intercom.Bool(true)}}}
savedTag, err := ic.Tags.Tag(&taggingList)

Segments

List

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

Find

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

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("[email protected]")
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.