intercom-dotnet

.NET bindings for the Intercom API

Project Updates

Maintenance

We're currently building a new team to provide in-depth and dedicated SDK support.

In the meantime, we'll be operating on limited capacity, meaning all pull requests will be evaluated on a best effort basis and will be limited to critical issues.

We'll communicate all relevant updates as we build this new team and support strategy in the coming months.

Installation
Resources
Authorization
Usage
Todo
Pull Requests

Add a dependency

nuget

Run the nuget command for installing the client as Install-Package Intercom.Dotnet.Client

Resources

Resources this API supports:

Users
Contacts
Companies
Admins
Events
Tags
Segments
Notes
Conversations
Counts

Each of these resources is represented through the dotnet client by a Class as ResourceClient.

E.g.: for users, you can use the UsersClient. For segments, you can use SegmentsClient.

Authorization

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.

You can set the Personal Access Token via creating an Authentication object by invoking the single paramter constructor:

UsersClient usersClient = new UsersClient(new Authentication("MyPersonalAccessToken"));

If you are building a third party application you will need to implement OAuth by following the steps for setting-up-oauth for Intercom.

Usage

For all client types

It is now possible to create all types of client by either supplying the authentication object instance or by providing an instance of the new RestClientFactory. The latter is the new preferred method to construct instances of the various clients. The older constructor methods have been marked as obsolete and will be removed in later versions.

Authentication auth = new Authentication("MyPersonalAccessToken");
RestClientFactory factory = new RestClientFactory(auth);
UsersClient usersClient = new UsersClient(factory);

Users

Create UsersClient instance

UsersClient usersClient = new UsersClient(new Authentication("MyPersonalAccessToken"));

Create user

User user = usersClient.Create(new User() { user_id = "my_id", name = "first last" });

View a user (by id, user_id or email)

User user = usersClient.View("100300231");
User user = usersClient.View(new User() { email = "example@example.com" });
User user = usersClient.View(new User() { id = "100300231" });
User user = usersClient.View(new User() { user_id = "my_id" });

Update a user with a company

User user = usersClient.Update(new User() {
                               email = "example@example.com",
                               companies = new List<Company>() {
                                           new Company() { company_id = "new_company" } } });

Update user's custom attributes

Dictionary<string, object> customAttributes = new Dictionary<string, object>();
customAttributes.Add("total", "100.00");
customAttributes.Add("account_level", "1");

User user = usersClient.View("100300231");
user.custom_attributes = customAttributes;

user = usersClient.Update(user);

List users and iterating through them

Limited to up to 10k records, if you want to list more records please use the Scroll API

Users users = usersClient.List();

foreach(User u in users.users)
    Console.WriteLine(u.email);

List users by Tag, Segment, Company

Dictionary<String, String> parameters = new Dictionary<string, string>();
parameters.Add("segment_id", "57553e93a32843ca09000277");
Users users = usersClient.List(parameters);

List users via the Scroll API

Users users = usersClient.Scroll();
String scroll_param_value = users.scroll_param;
Users users = usersClient.Scroll(scroll_param_value);

Delete a user

usersClient.Archive("100300231"); // with intercom generated user's id
usersClient.Archive(new User() { email = "example@example.com" });
usersClient.Archive(new User() { user_id = "my_id" });

Permanently delete a user

usersClient.PermanentlyDeleteUser("100300231"); // with intercom generated user's id

Update User's LastSeenAt (multiple ways)

User user = usersClient.UpdateLastSeenAt("100300231");
User user = usersClient.UpdateLastSeenAt(new User() { id = "100300231" });
User user = usersClient.UpdateLastSeenAt("100300231", 1462110718);
User user = usersClient.UpdateLastSeenAt(new User() { id = "100300231" }, 1462110718);

Increment User's Session

usersClient.IncrementUserSession(new User() { id = "100300231" });
usersClient.IncrementUserSession("100300231", new List<String>() { "company_is_blue" }});

// You can also update a User's session by updating a User record with a "new_session = true" attribute

Removing User's companies

User user = usersClient.RemoveCompanyFromUser("100300231", new List<String>() { "true_company" });

Contacts

Create ContactsClient instance

ContactsClient contactsClient = new ContactsClient(new Authentication("MyPersonalAccessToken"));

Create a contact

Contact contact = contactsClient.Create(new Contact() { });
Contact contact = contactsClient.Create(new Contact() { name = "lead_name" });

View a contact (by id, or user_id)

Contact contact = contactsClient.View("100300231");
Contact contact = contactsClient.View(new Contact() { id = "100300231" });
Contact contact = contactsClient.View(new Contact() { user_id = "my_lead_id" });

Update a contact (by id, or user_id)

Contact contact = contactsClient.Update(
                    new Contact()
                    {   
                        email = "example@example",
                        companies = new List<Company>() { new Company() { company_id = "new_company" } }
                    });

List contacts and iterate through them

Limited to up to 10k records, if you want to list more records please use the Scroll API

Contacts contacts = contactsClient.List();

foreach (Contact c in contacts.contacts)
    Console.WriteLine(c.email);

List contacts by email

Contacts contacts = contactsClient.List("email@example.com");

List contacts via Scroll API

Contacts contacts = contactsClient.Scroll();
String scroll_param_value = contacts.scroll_param;
Contacts contacts = contactsClient.Scroll(scroll_param_value);

Convert a contact to a User

Note that if the user does not exist they will be created, otherwise they will be merged.

User user = contactsClient.Convert(contact, new User() { user_id = "120" });

Delete a contact

contactsClient.Delete("100300231");
contactsClient.Delete(new Contact() { id = "100300231" });
contactsClient.Delete(new Contact() { user_id = "my_id" });

Visitors

Create VisitorsClient instance

VisitorsClient visitorsClient = new VisitorsClient(new Authentication("MyPersonalAccessToken"));

View a visitor

Visitor visitor = VisitorsClient.View("573479f784c5acde6a000575");

View a visitor by user_id

Dictionary<String, String> parameters = new Dictionary<string, string>();
parameters.Add("user_id", "16e690c0-485a-4e87-ae98-a326e788a4f7");
Visitor visitor = VisitorsClient.View(parameters);

Update a visitor

Visitor visitor = VisitorsClient.Update(visitor);

Delete a visitor

Visitor visitor = VisitorsClient.Delete(visitor);

Convert to existing user

Visitor visitor = VisitorsClient.ConvertToUser(visitor, user);

Convert to new user

Visitor visitor = VisitorsClient.ConvertToUser(visitor, new User(){ user_id = "25" });

Convert to contact

Visitor visitor = VisitorsClient.ConvertToContact(visitor);

Companies

Create CompanyClient instance

CompanyClient companyClient = new CompanyClient(new Authentication("MyPersonalAccessToken"));

Create a company

Company company = companyClient.Create(new Company());
Company company = companyClient.Create(new Company() { name = "company_name" });

View a company

Company company = companyClient.View("100300231");
Company company = companyClient.View(new Company() { id = "100300231" });
Company company = companyClient.View(new Company() { company_id = "my_company_id" });
Company company = companyClient.View(new Company() { name = "my_company_name" });

Update a company

Company company = companyClient.Update(
                    new Company()
                    {   
                        company_id = "example@example",
                        monthly_spend = 100
                    });

List companies

Limited to up to 10k records, if you want to list more records please use the Scroll API

Companies companies = companyClient.List();

List companies via Scroll API

Companies companies = companyClient.Scroll();
String scrollParam = companies.scroll_param;
Companies companies = companyClient.Scroll(scrollParam);

foreach (Company c in companies.companies)
    Console.WriteLine(c.name);

List a Company's registered users

Users users = companyClient.ListUsers(new Company() { id = "100300231" });
Users users = companyClient.ListUsers(new Company() { company_id = "my_company_id" });

Admins

Create AdminsClient instance

AdminsClient adminsClient = new AdminsClient(new Authentication("MyPersonalAccessToken"));

View an admin

Admin admin = adminsClient.View("100300231");
Admin admin = adminsClient.View(new Admin() { id = "100300231" });

List admins

Admins admins = adminsClient.List();

Segments

Create SegmentsClient instance

SegmentsClient segmentsClient = new SegmentsClient(new Authentication("MyPersonalAccessToken"));

View a segment (by id)

Segment segment = segmentsClient.View("100300231");
Segment segment = segmentsClient.View(new Segment() { id = "100300231" });

List segments

Segments segments = segmentsClient.List();

Notes

Create NotesClient instance

NotesClient notesClient = new NotesClient(new Authentication("MyPersonalAccessToken"));

Create a note (by User, body and admin_id)

Note note = notesClient.Create(
    new Note() {
    author = new Author() { id = "100300231_admin_id" },
    user =  new User() { email = "example@example.com" },
    body = "this is a new note"
});

Note note = notesClient.Create(new User() { email = "example@example.com" }, "this is a new note", "100300231_admin_id");

View a note

Note note = notesClient.View("2001");

List User's notes

Notes notes = notesClient.List(new User() { id = "100300231"});

foreach (Note n in notes.notes)
    Console.WriteLine(n.user.name);

Events

Create EventsClient instance

EventsClient eventsClient = new EventsClient(new Authentication("MyPersonalAccessToken"));

Create an event

Event ev = eventsClient.Create(new Event() { user_id = "1000_user_id", email = "user_email@example.com", event_name = "new_event", created_at = 1462110718  });

Create an event with Metadata (Simple, MonetaryAmounts and RichLinks)

Metadata metadata = new Metadata();
metadata.Add("simple", 100);
metadata.Add("simple_1", "two");
metadata.Add("money", new Metadata.MonetaryAmount(100, "eur"));
metadata.Add("richlink", new Metadata.RichLink("www.example.com", "value1"));

Event ev = eventsClient.Create(new Event() { user_id = "1000_user_id", email = "user_email@example.com", event_name = "new_event", created_at = 1462110718, metadata = metadata  });

List events by user

Events events = eventsClient.List(new User() { user_id = "my_id" });

Counts

Create CountsClient instance

CountsClient countsClient = new CountsClient(new Authentication("MyPersonalAccessToken"));

Get AppCount

AppCount appCount = countsClient.GetAppCount();

Get Specific Counts

ConversationAppCount conversationAppCount = countsClient.GetConversationAppCount();
ConversationAdminCount conversationAdminCount = countsClient.GetConversationAdminCount();
CompanySegmentCount companySegmentCount = countsClient.GetCompanySegmentCount();
CompanyTagCount companyTagCount = countsClient.GetCompanyTagCount();
CompanyUserCount companyUserCount = countsClient.GetCompanyUserCount();
UserSegmentCount userSegmentCount = countsClient.GetUserSegmentCount();
UserTagCount userTagCount = countsClient.GetUserTagCount();

Conversations

Create ConversationsClient instance

ConversationsClient conversationsClient = new ConversationsClient(new Authentication("MyPersonalAccessToken"));

View any type of conversation

conversationsClient.View("100300231");
conversationsClient.View("100300231", displayAsPlainText: true);

List all conversations

conversationsClient.ListAll();

Dictionary<String, String> parameters = new Dictionary<string, string>();
parameters.Add("order", "asc");
conversationsClient.ListAll(parameters);

Create AdminConversationsClient instance

AdminConversationsClient adminConversationsClient = new AdminConversationsClient(new Authentication("MyPersonalAccessToken"));

Create Admin initiated Conversation

AdminConversationMessage admin_message =
    adminConversationsClient.Create(new AdminConversationMessage(
            from: new AdminConversationMessage.From("1000_admin_id"),
            to: new AdminConversationMessage.To(id: "1000_user_id"),
            message_type: AdminConversationMessage.MessageType.EMAIL,
            template: AdminConversationMessage.MessageTemplate.PERSONAL,
            subject: "this is a subject",
            body: "this is an email body"));

Create Admin initiated Conversation's reply

Conversation conversation =
    adminConversationsClient.Reply(
        new AdminConversationReply(
            conversationId: "1000_conversation_id",
            adminId: "1000_admin_id",
            messageType: AdminConversationReply.ReplyMessageType.COMMENT,
            body: "this is a reply body"));

Reply to user's last conversation

Conversation reply =
    adminConversationsClient.ReplyLastConversation(
        new AdminLastConversationReply()
        {
            admin_id = "12434",
            message_type = "comment",
            body = "replying to last conversation",
            intercom_user_id = "5911bd8bf0c7446d2d1d045d"
        });

Create UserConversationsClient instance

UserConversationsClient userConversationsClient = new UserConversationsClient(new Authentication("MyPersonalAccessToken"));

Create User initiated Conversation

UserConversationMessage user_message =
    userConversationsClient.Create(
        new UserConversationMessage(
            from: new UserConversationMessage.From(id: "1000_user_id"),
            body: "this is a user's message body"));

Create User initiated Conversation's reply

Conversation conversation =
    userConversationsClient.Reply(
        new UserConversationReply(
            conversationId: "1000_conversation_id",
            body: "this is a user's reply body",
            attachementUrls: new List<String>() { "www.example.com/example.png", "www.example.com/example.txt" }));

Webhooks & Pagination

Not yet supported by these bindings.

Todo

[ ] Increase test coverage
[ ] Support Pagination
[ ] Support Webhooks
[ ] Support Async
[ ] Have 100% feature parity with curl

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.

intercom / intercom-dotnet

readme

intercom-dotnet

Project Updates

Maintenance

Add a dependency

nuget

Resources

Authorization

Usage

For all client types

Users

Create UsersClient instance

Create user

View a user (by id, user_id or email)

Update a user with a company

Update user's custom attributes

List users and iterating through them

List users by Tag, Segment, Company

List users via the Scroll API

Delete a user

Permanently delete a user

Update User's LastSeenAt (multiple ways)

Increment User's Session

Removing User's companies

Contacts

Create ContactsClient instance

Create a contact

View a contact (by id, or user_id)

Update a contact (by id, or user_id)

List contacts and iterate through them

List contacts by email

List contacts via Scroll API

Convert a contact to a User

Delete a contact

Visitors

Create VisitorsClient instance

View a visitor

View a visitor by user_id

Update a visitor

Delete a visitor

Convert to existing user

Convert to new user

Convert to contact

Companies

Create CompanyClient instance

Create a company

View a company

Update a company

List companies

List companies via Scroll API

List a Company's registered users

Admins

Create AdminsClient instance

View an admin

List admins

Tags

Create TagsClient instance

Create a tag

List tags

Delete a tag

Tag User, Company or Contact

Untag User, Company or Contact

Segments

Create SegmentsClient instance

View a segment (by id)

List segments

Notes

Create NotesClient instance

Create a note (by User, body and admin_id)

View a note

List User's notes

Events

Create EventsClient instance

Create an event

Create an event with Metadata (Simple, MonetaryAmounts and RichLinks)

List events by user

Counts

Create CountsClient instance

Get AppCount