Thin client for the Intercom API.
Currently in beta, though breaking API changes are not expected.
go get gopkg.in/intercom/intercom-go.v1
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 (
`gopkg.in/intercom/intercom-go.v1`
)
ic := intercom.NewClient("appID", "apiKey")
This client can then be used to make requests.
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"))
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
, orEmail
is 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{
{ID: "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("[email protected]")
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{})
user, err := ic.Users.Delete("46adad3f09126dca")
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 // []Contact
contactList, err := ic.Contacts.ListByEmail("[email protected]", intercom.PageParams{})
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)
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: "[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.
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.
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 // []Companies
companyList, err := ic.Companies.ListBySegment("segmentID123", intercom.PageParams{})
companyList, err := ic.Companies.ListByTag("42", intercom.PageParams{})
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
, orEmail
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 passedmap[string]interface{}
.
adminList, err := ic.Admins.List()
admins := adminList.Admins
tagList, err := ic.Tags.List()
tags := tagList.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.
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 := segmentList.Segments
segment := ic.Segments.Find("abc312daf2397")
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.
msg := intercom.NewInAppMessage(intercom.Admin{ID: "1234"}, intercom.Contact{Email: "[email protected]"}, "body")
savedMessage, err := ic.Messages.Save(&msg)
msg := intercom.NewUserMessage(intercom.User{Email: "[email protected]"}, "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)
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)
}
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.