Go Reference • Releases • Go 1.24+ • MIT License

Quick start • Migrate from v2 • Why intercom-go? • Examples • API coverage • Production

_{About the name: The company formerly known as Intercom became Fin in May 2026. Intercom remains the helpdesk and versioned API, so this module remains intercom-go.}

Why intercom-go?

Generated where it should be. Hand-shaped where it matters.

Capability	What you get
Idiomatic Go API	Use focused services such as client.Admins.Me(ctx), client.Contacts.Search(ctx, ...), and client.Conversations.Reply(ctx, ...) instead of generated operation names and unions.
Production-minded	Opt into conservative retries, inspect request IDs and rate limits, customize individual requests, and verify webhook signatures.
Complete and current	Public services account for every operation in the pinned Intercom API 2.15 specification, with an automated coverage audit.
Stable public surface	Generated OpenAPI code stays internal while compatibility checks protect the SDK API your application imports.
Easy to test	The public intercomtest package scripts local Intercom responses and captures outgoing requests without calling Intercom.

Install

go get github.com/uffejaeger/intercom-go@latest

import intercom "github.com/uffejaeger/intercom-go"

Go records the selected release in your module files. Review SDK upgrades like other production dependency changes rather than tracking an unreviewed branch.

Quick Start

Set INTERCOM_ACCESS_TOKEN, then create a client and call a service:

package main

import (
	"context"
	"fmt"
	"log"

	intercom "github.com/uffejaeger/intercom-go"
)

func main() {
	client, err := intercom.NewClientFromEnv()
	if err != nil {
		log.Fatal(err)
	}

	admin, err := client.Admins.Me(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(*admin.Email)
}

Pass a token directly or select the EU or Australian Intercom region with client options:

client, err := intercom.NewClient("access-token", intercom.WithRegion(intercom.EU))

Migrating from the legacy v2 client

intercom-go is an independent, community-maintained SDK rather than a drop-in replacement for gopkg.in/intercom/intercom-go.v2. It uses the current Intercom API model and requires a context.Context on each service call. The migration guide maps common workflows and calls out the deliberate API differences.

Everyday API

Retrieve and search contacts

contact, err := client.Contacts.Get(ctx, "contact_id")

contacts, err := client.Contacts.Search(ctx, intercom.ContactSearch{
	Field:    "email",
	Operator: intercom.ContactSearchEquals,
	Value:    "customer@example.com",
	PerPage:  25,
})

Paginate results

Use explicit page options:

calls, err := client.Calls.ListWithOptions(ctx, intercom.PageOptions{
	Page:    2,
	PerPage: 25,
})

conversations, err := client.Conversations.ListWithOptions(ctx, intercom.CursorPageOptions{
	PerPage:       50,
	StartingAfter: "cursor",
})

Or iterate through cursor-paginated results lazily:

iter := client.Conversations.ListIter(ctx, intercom.CursorPageOptions{PerPage: 50})
for iter.Next() {
	conversation := iter.Conversation()
	log.Printf("conversation id=%s", *conversation.Id)
}
if err := iter.Err(); err != nil {
	if errors.Is(err, intercom.ErrPaginationStalled) {
		// Intercom returned a cursor that was already requested.
	}
	return err
}

Handle API errors

contact, err := client.Contacts.Get(ctx, "missing")
if err != nil {
	if intercom.IsNotFound(err) {
		return nil
	}

	var apiErr *intercom.ErrorResponse
	if errors.As(err, &apiErr) {
		log.Printf("intercom status=%d request_id=%s retry_after=%s",
			apiErr.StatusCode, apiErr.RequestID, apiErr.Headers.Get("Retry-After"))
	}
	return err
}

Production-ready HTTP

Conservative retries

Retries are opt-in:

client, err := intercom.NewClient("access-token", intercom.WithRetry(intercom.RetryConfig{
	MaxAttempts: 3,
}))

The retry policy honors Intercom's X-RateLimit-Reset header for rate limits, falls back to Retry-After, and retries selected transient failures. Mutating requests are not retried unless AllowUnsafeMethods is set.

Response metadata

Observe attempts, request IDs, and rate-limit information without changing service method signatures:

client, err := intercom.NewClient("access-token", intercom.WithResponseHook(func(info intercom.ResponseInfo) {
	log.Printf("intercom attempt=%d/%d status=%d request_id=%s remaining=%s",
		info.Attempt, info.MaxAttempts, info.StatusCode, info.RequestID, info.RateLimitRemaining)
}))

Per-request options

Override headers, query parameters, or retry behavior for one call:

ctx, err = intercom.WithRequestOptions(ctx, intercom.RequestOptions{
	Headers: http.Header{"X-Correlation-Id": []string{correlationID}},
	Query:   url.Values{"custom": []string{"value"}},
	Retry:   &intercom.RetryConfig{MaxAttempts: 1}, // Disable retries for this call.
})
contact, err := client.Contacts.Get(ctx, "contact_id")

See the production guide for HTTP client configuration, deadlines, retry safety, rate limits, and observability.

Webhooks

Parse and verify webhook notifications in one step:

event, err := intercom.ParseAndVerifyWebhook(r, clientSecret, 0)
if err != nil {
	return err
}

log.Printf("intercom webhook topic=%s id=%s", event.Topic, event.ID)

ParseAndVerifyWebhook limits the body to 1 MiB by default, verifies X-Hub-Signature over the exact bytes received, and then parses the event. Use VerifyWebhookSignature and ParseWebhookPayload separately when the application already owns the raw payload bytes.

API Coverage

The SDK targets Intercom API version 2.15, pinned in spec/intercom.openapi.yaml. Public root-package services cover the pinned specification while generated client code stays internal under internal/generated/intercom.

• Public SDK coverage audit
• Production usage
• Go compatibility, releases, and v1 criteria
• Public API compatibility audit
• Spec normalization and client generation

Runnable Examples

• examples/identify_admin
• examples/search_contacts
• examples/list_conversations
• examples/observe_rate_limits
• examples/verify_webhook

Support and Security

• Use the support guidance for usage questions and maintenance expectations.
• Report security issues through GitHub's private vulnerability reporting flow.
• Read CONTRIBUTING.md before proposing a change.

Trademark Notice

The Fin and Intercom names and logos are trademarks or service marks of Intercom, Inc. or its affiliates in the U.S. and other countries. The Go trademark and Go logo are trademarks of Google LLC. Their inclusion does not imply affiliation, sponsorship, or endorsement.

License

MIT