Thin client for the Intercom API.
go get gopkg.in/intercom/intercom-go.v2
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)
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.
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 infoor combined:
ic.Option(intercom.TraceHTTP(true), intercom.BaseURI("http://intercom.dev"))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, orEmailis required. SignedUpAt(optional), like all dates in the client, must be an integer(32) representing seconds since Unix Epoch.
Adding a Company:
companyList := intercom.CompanyList{
Companies: []intercom.Company{
{CompanyID: "5"},
},
}
user := intercom.User{
UserID: "27",
Companies: &companyList,
}Removing is similar, but adding a Remove: intercom.Bool(true) attribute to a company.
user, err := ic.Users.FindByID("46adad3f09126dca")user, err := ic.Users.FindByUserID("27")user, err := ic.Users.FindByEmail("test@example.com")userList, err := ic.Users.List(intercom.PageParams{Page: 2})
userList.Pages // page information
userList.Users // []UseruserList, 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{})user, err := ic.Users.Delete("46adad3f09126dca")In the Intercom API we refer to contacts as leads. See here for more info We did not change this in the SDK since that would be a major breaking change. This is something we will address shortly. So any reference to contacts in the SDK is a reference to a lead in Intercom
contact, err := ic.Contacts.FindByID("46adad3f09126dca")contact, err := ic.Contacts.FindByUserID("27")contactList, err := ic.Contacts.List(intercom.PageParams{Page: 2})
contactList.Pages // page information
contactList.Contacts // []ContactcontactList, err := ic.Contacts.Scroll("")
scrollParam = contactList.ScrollParam
contactList, err := ic.Contacts.Scroll(scrollParam)contactList, err := ic.Contacts.ListByEmail("test@example.com", intercom.PageParams{})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)
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.
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.
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)CompanyIDis required.
company, err := ic.Companies.FindByID("46adad3f09126dca")company, err := ic.Companies.FindByCompanyID("27")company, err := ic.Companies.FindByName("My Co")companyList, err := ic.Companies.List(intercom.PageParams{Page: 2})
companyList.Pages // page information
companyList.Companies // []CompaniescompanyList, err := ic.Companies.ListBySegment("segmentID123", intercom.PageParams{})companyList, err := ic.Companies.ListByTag("42", intercom.PageParams{})userList, err := ic.Companies.ListUsersByID("46adad3f09126dca", intercom.PageParams{})
userList.Users // []UseruserList, err := ic.Companies.ListUsersByCompanyID("27", intercom.PageParams{})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, orEmailis required (With leads you need to use ID). EventNameis required.CreatedAtis required, must be an integer representing seconds since Unix Epoch. Will be set to now unless given.Metadatais optional, and can be constructed using the helper as above, or as a passedmap[string]interface{}.
adminList, err := ic.Admins.List()
admins := adminList.AdminstagList, err := ic.Tags.List()
tags := tagList.Tagstag := 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.
err := ic.Tags.Delete("6")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)segmentList := ic.Segments.List()
segments, err := segmentList.Segmentssegment, err := ic.Segments.Find("abc312daf2397")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.
msg := intercom.NewInAppMessage(intercom.Admin{ID: "1234"}, intercom.Contact{Email: "test@example.com"}, "body")
savedMessage, err := ic.Messages.Save(&msg)msg := intercom.NewUserMessage(intercom.User{Email: "test@example.com"}, "body")
savedMessage, err := ic.Messages.Save(&msg)convo, err := intercom.Conversations.Find("1234")convoList, err := intercom.Conversations.ListAll(intercom.PageParams{})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{})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{})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:
convo, err := intercom.Conversations.Open("1234", &openerAdmin)Close:
convo, err := intercom.Conversations.Close("1234", &closerAdmin)convo, err := intercom.Conversations.Assign("1234", &assignerAdmin, &assigneeAdmin)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 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)
}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!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.
-
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.