Intercom Go SDK

Intercom Go SDK Examples

📘

Installation and Configuration Steps

For information on how to install and configure the Intercom Ruby Go please see the intercom-go github page. For general code examples please see below.

📘

Go Docker Image

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

Create Client Using Access Tokens

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

Note that you can also use the goth library to help setup your OAuth with Intercom

Client Configuation Options

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

Configure the client

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

Create/delete a user

Create a user

user := intercom.User{
       	UserID: "27",
       	Email: "[email protected]",
       	Name: "InterGopher",
       	SignedUpAt: int64(time.Now().Unix()),
       	CustomAttributes: map[string]interface{}{"is_cool": true},
}
savedUser, err := ic.Users.Save(&user)

Delete a user

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

📘

user_id or email

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 to/from users

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 users

Find by User ID

user, err := ic.Users.FindByUserID("27")

Find by User Email

user, err := ic.Users.FindByEmail("[email protected]")

Find by ID

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

List users

List users

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

List users by segment

userList, err := ic.Users.ListBySegment("segmentID123", intercom.PageParams{})

List users by tag

userList, err := ic.Users.ListByTag("42", intercom.PageParams{})

Contacts

📘

Leads <=> Contacts

Leads were previously known as 'Contacts'. Our object names and types continue to be referred to as 'contacts/contact'. We will migrate to 'Leads/Lead' models at a future date

Find Contacts (Leads)

Find by ID

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

Find by User ID

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

List Contacts (Leads)

List contacts

contactList, err := ic.Contacts.List(intercom.PageParams{Page: 2})
contactList.Pages // page information
contactList.Contacts // []Contact

List contacts by Email

contactList, err := ic.Contacts.ListByEmail("[email protected]", intercom.PageParams{})

Create a contact(lead)

Create a Contact (Lead)

contact := intercom.Contact{
       	Email: "[email protected]",
       	Name: "SomeContact",
       	CustomAttributes: map[string]interface{}{"is_cool": true},
}
savedContact, err := ic.Contacts.Create(&contact)

📘

Identified ignored for Contacts (Leads)

No identifier is required. Set values for UserID will be ignored (consider creating Users instead)

Update Contacts

Install Contacts

contact := intercom.Contact{
       	UserID: "abc-13d-3",
       	Name: "SomeContact",
       	CustomAttributes: map[string]interface{}{"is_cool": true},
}
savedContact, err := ic.Contacts.Update(&contact)

📘

Updating needs UserID or ID

ID or UserID is required. Will not create new contacts

Convert a contact(lead) to a user

Used to convert a Contact into a User

Convert contact (Leads) into Users

contact := intercom.Contact{
       	UserID: "abc-13d-3",
}
user := intercom.User{
       	Email: "[email protected]",
}
savedUser, err := ic.Contacts.Convert(&contact, &user)

📘

What if I already have a 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

Create a company

Create a company

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 Companies

Find by User ID

company, err := ic.Companies.FindByCompanyID("27")

Find by User name

company, err := ic.Companies.FindByName("My Co")

Find by ID

company, err := ic.Companies.FindByID("46adad3f09126dca")

List Companies

List companies

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

List companies by segment

companyList, err := ic.Companies.ListBySegment("segmentID123", intercom.PageParams{})

List companies by tag

companyList, err := ic.Companies.ListByTag("42", intercom.PageParams{})

Events

Create events

Create an event

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)

Admins

List admins

List Admins

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

Tags

List Tags

List Tags

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

Create/delete tags

Save tags

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 tags

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

Tagging Users/Companies

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

Tagging Users

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

Untagging Users

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

Segments

List segments

List Segments

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

Find segments

Find Segments

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

Messages

Message from admin to user/contact via email

Message from admin to user

msg := intercom.NewEmailMessage(intercom.PERSONAL_TEMPLATE, intercom.Admin{ID: "1234"}, intercom.User{Email: "[email protected]"}, "subject", "body")
savedMessage, err := ic.Messages.Save(&msg)
//Can use intercom.PLAIN_TEMPLATE too, or replace the intercom.User with an intercom.Contact.

Message from admin to user/contact InApp

Admin to user InApp message

msg := intercom.NewInAppMessage(intercom.Admin{ID: "1234"}, intercom.Contact{Email: "[email protected]"}, "body")
savedMessage, err := ic.Messages.Save(&msg)

New User Message

New user message

msg := intercom.NewUserMessage(intercom.User{Email: "[email protected]"}, "body")
savedMessage, err := ic.Messages.Save(&msg)

Conversations

Find conversations

Find a conversation by ID

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

List conversations

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

List Conversations By User

Show all for users

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

Show all unread for users

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

List Conversations by Admin

Conversations by admin

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

Open Conversations for admin

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

Closed Conversations for admin

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

Replying to conversations

Reply to a conversation

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

Reply to a conversation with attachment

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

User conversation 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 an admin conversation

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

Close an admin conversation

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

Assign an admin conversation

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

Errors

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

Go error handling

_, err := ic.Users.FindByEmail("[email protected]")
if herr, ok := err.(intercom.IntercomError); ok && herr.GetCode() == "not_found" {
       	fmt.Print(herr)
}

HTTP Client

📘

HTTP Client Options

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 outlined below.

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.

Intercom client

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

On Bools

❗️

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.