intercom

仓库: vm0-ai/vm0-skills
安装量: 49
排名: #15225

安装

npx skills add https://github.com/vm0-ai/vm0-skills --skill intercom

Intercom API Manage customer conversations, contacts, messages, articles, and support operations via the Intercom REST API. Official docs: https://developers.intercom.com/docs When to Use Use this skill when you need to: Manage contacts - Create, update, search, and delete user profiles Handle conversations - List, search, reply to, assign, and close conversations Send messages - Create and send messages to contacts Manage companies - Track organizations and their members Work with articles - Access help center content and knowledge base Add notes - Annotate contact profiles with internal notes Use tags - Organize contacts and conversations with labels Track events - Record custom user activities and behaviors Manage tickets - Create and handle support tickets Prerequisites Setup API Wrapper Create a helper script for API calls: cat

/tmp/intercom-curl << 'EOF'

!/bin/bash

curl -s -H "Content-Type: application/json" -H "Authorization: Bearer $INTERCOM_TOKEN" "$@"
EOF
chmod
+x /tmp/intercom-curl
Usage:
All examples below use
/tmp/intercom-curl
instead of direct
curl
calls.
Getting Your Access Token
Log in to your
Intercom workspace
Navigate to
Settings
→
Developers
→
Developer Hub
Create a new app or select an existing one
Go to
Configure
→
Authentication
Copy your
Access Token
export
INTERCOM_TOKEN
=
"your_access_token"
Verify Token
Test your token:
/tmp/intercom-curl
"https://api.intercom.io/admins"
|
jq
'.admins[] | {id, name, email}'
Expected response: List of admins in your workspace
✅ This skill has been tested and verified
with a live Intercom workspace. All core endpoints work correctly.
Regional Endpoints
US (Default)
:
https://api.intercom.io/
Europe
:
https://api.eu.intercom.io/
Australia
:
https://api.au.intercom.io/
How to Use
All examples assume
INTERCOM_TOKEN
is set.
Base URL
:
https://api.intercom.io/
Required Headers
:
Authorization: Bearer ${INTERCOM_TOKEN}
Accept: application/json
Intercom-Version: 2.14
Core APIs
1. List Admins
Get all admins/teammates in your workspace:
/tmp/intercom-curl
"https://api.intercom.io/admins"
|
jq
'.admins[] | {id, name, email}'
2. Create Contact
Create a new contact (lead or user):
Write to
/tmp/intercom_request.json
:
{
"email"
:
"user@example.com"
,
"name"
:
"John Doe"
,
"phone"
:
"+1234567890"
}
Then run:
/tmp/intercom-curl
-X
POST
"https://api.intercom.io/contacts"
-d
@/tmp/intercom_request.json
With custom attributes:
Write to
/tmp/intercom_request.json
:
{
"email"
:
"user@example.com"
,
"name"
:
"John Doe"
,
"custom_attributes"
:
{
"plan"
:
"premium"
,
"signup_date"
:
"2024-01-15"
}
}
Then run:
/tmp/intercom-curl
-X
POST
"https://api.intercom.io/contacts"
-d
@/tmp/intercom_request.json
3. Get Contact
Retrieve a specific contact by ID. Replace
with the actual contact ID:
curl
-s
"https://api.intercom.io/contacts/"
-H
"Authorization: Bearer
${INTERCOM_TOKEN}
"
-H
"Accept: application/json"
-H
"Intercom-Version: 2.14"
4. Update Contact
Update contact information. Replace
with the actual contact ID:
Write to
/tmp/intercom_request.json
:
{
"name"
:
"Jane Doe"
,
"custom_attributes"
:
{
"plan"
:
"enterprise"
}
}
Then run:
curl
-s
-X
PATCH
"https://api.intercom.io/contacts/"
-H
"Authorization: Bearer
${INTERCOM_TOKEN}
"
-H
"Content-Type: application/json"
-H
"Accept: application/json"
-H
"Intercom-Version: 2.14"
-d
@/tmp/intercom_request.json
Note
Newly created contacts may need a few seconds before they can be updated. 5. Delete Contact Permanently delete a contact. Replace with the actual contact ID: curl -s -X DELETE "https://api.intercom.io/contacts/" -H "Authorization: Bearer ${INTERCOM_TOKEN} " -H "Accept: application/json" -H "Intercom-Version: 2.14" 6. Search Contacts Search contacts with filters: Write to /tmp/intercom_request.json : { "query" : { "field" : "email" , "operator" : "=" , "value" : "user@example.com" } } Then run: /tmp/intercom-curl -X POST "https://api.intercom.io/contacts/search" -d @/tmp/intercom_request.json | jq '.data[] | {id, email, name}' Search with multiple filters: Write to /tmp/intercom_request.json : { "query" : { "operator" : "AND" , "value" : [ { "field" : "role" , "operator" : "=" , "value" : "user" } , { "field" : "custom_attributes.plan" , "operator" : "=" , "value" : "premium" } ] } } Then run: /tmp/intercom-curl -X POST "https://api.intercom.io/contacts/search" -d @/tmp/intercom_request.json | jq '.data[] | {id, email, name}' 7. List Conversations Get all conversations: /tmp/intercom-curl "https://api.intercom.io/conversations?order=desc&sort=updated_at" | jq '.conversations[] | {id, state, created_at, updated_at}' 8. Get Conversation Retrieve a specific conversation. Replace with the actual conversation ID: /tmp/intercom-curl "https://api.intercom.io/conversations/" 9. Search Conversations Search for open conversations: Write to /tmp/intercom_request.json : { "query" : { "operator" : "AND" , "value" : [ { "field" : "state" , "operator" : "=" , "value" : "open" } ] } } Then run: /tmp/intercom-curl -X POST "https://api.intercom.io/conversations/search" -d @/tmp/intercom_request.json | jq '.conversations[] | {id, state, created_at}' Search by assignee: Replace with the actual admin ID in the request JSON below. Write to /tmp/intercom_request.json : { "query" : { "field" : "admin_assignee_id" , "operator" : "=" , "value" : "" } } Then run: /tmp/intercom-curl -X POST "https://api.intercom.io/conversations/search" -d @/tmp/intercom_request.json | jq '.conversations[] | {id, state, created_at}' 10. Reply to Conversation Reply as an admin. Replace and with actual IDs: Write to /tmp/intercom_request.json : { "message_type" : "comment" , "type" : "admin" , "admin_id" : "" , "body" : "Thank you for your message. We'll help you with this." } Then run: /tmp/intercom-curl -X POST "https://api.intercom.io/conversations//parts" -d @/tmp/intercom_request.json 11. Assign Conversation Assign a conversation to an admin or team. Replace , , and with actual IDs: Write to /tmp/intercom_request.json : { "message_type" : "assignment" , "type" : "admin" , "admin_id" : "" , "assignee_id" : "" } Then run: /tmp/intercom-curl -X POST "https://api.intercom.io/conversations//parts" -d @/tmp/intercom_request.json 12. Close Conversation Close an open conversation. Replace and with actual IDs: Write to /tmp/intercom_request.json : { "message_type" : "close" , "type" : "admin" , "admin_id" : "" } Then run: /tmp/intercom-curl -X POST "https://api.intercom.io/conversations//parts" -d @/tmp/intercom_request.json 13. Create Note Add an internal note to a contact. Replace with the actual contact ID: Write to /tmp/intercom_request.json : { "body" : "Customer is interested in enterprise plan. Follow up next week." } Then run: /tmp/intercom-curl -X POST "https://api.intercom.io/contacts//notes" -d @/tmp/intercom_request.json 14. List Tags Get all tags: /tmp/intercom-curl "https://api.intercom.io/tags" | jq '.data[] | {id, name}' 15. Create Tag Create a new tag: Write to /tmp/intercom_request.json : { "name" : "VIP Customer" } Then run: /tmp/intercom-curl -X POST "https://api.intercom.io/tags" -d @/tmp/intercom_request.json 16. Tag Contact Add a tag to a contact. Replace and with actual IDs: Write to /tmp/intercom_request.json : { "id" : "" } Then run: /tmp/intercom-curl -X POST "https://api.intercom.io/contacts//tags" -d @/tmp/intercom_request.json 17. Untag Contact Remove a tag from a contact. Replace and with actual IDs: curl -s -X DELETE "https://api.intercom.io/contacts//tags/" -H "Authorization: Bearer ${INTERCOM_TOKEN} " -H "Intercom-Version: 2.14" 18. List Articles Get help center articles: /tmp/intercom-curl "https://api.intercom.io/articles" | jq '.data[] | {id, title, url}' 19. Get Article Retrieve a specific article. Replace with the actual article ID: /tmp/intercom-curl "https://api.intercom.io/articles/" 20. Create Company Create a new company: Write to /tmp/intercom_request.json : { "company_id" : "acme-corp-123" , "name" : "Acme Corporation" , "plan" : "enterprise" , "size" : 500 , "website" : "https://acme.com" } Then run: /tmp/intercom-curl -X POST "https://api.intercom.io/companies" -d @/tmp/intercom_request.json 21. Attach Contact to Company Associate a contact with a company. Replace and with actual IDs: Write to /tmp/intercom_request.json : { "id" : "" } Then run: /tmp/intercom-curl -X POST "https://api.intercom.io/contacts//companies" -d @/tmp/intercom_request.json 22. Track Event Record a custom event for a contact: Write to /tmp/intercom_request.json : { "event_name" : "purchased-plan" , "created_at" : 1234567890 , "user_id" : "user-123" , "metadata" : { "plan" : "premium" , "price" : 99 } } Then run: /tmp/intercom-curl -X POST "https://api.intercom.io/events" -d @/tmp/intercom_request.json Common Workflows Find and Reply to Open Conversations Write to /tmp/intercom_request.json : { "query" : { "field" : "state" , "operator" : "=" , "value" : "open" } } Then run:

Search for open conversations

OPEN_CONVS

" $( /tmp/intercom-curl -X POST "https://api.intercom.io/conversations/search" -d @/tmp/intercom_request.json ) "

Replace with the actual admin ID

ADMIN_ID

"" Write to /tmp/intercom_request.json : { "message_type" : "comment" , "type" : "admin" , "admin_id" : "" , "body" : "We're looking into this for you." } Then run: /tmp/intercom-curl -X POST "https://api.intercom.io/conversations/ ${OPEN_CONVS} /parts" -d @/tmp/intercom_request.json Create Contact and Add to Company Write to /tmp/intercom_request.json : { "email" : "newuser@acme.com" , "name" : "New User" } Then run:

Create contact and extract ID

CONTACT_ID

$( /tmp/intercom-curl -X POST "https://api.intercom.io/contacts" -d @/tmp/intercom_request.json )

Replace with the actual company ID

COMPANY_ID

""
Write to
/tmp/intercom_request.json
:
{
"id"
:
""
}
Then run:
/tmp/intercom-curl
-X
POST
"https://api.intercom.io/contacts/
${CONTACT_ID}
/companies"
-d
@/tmp/intercom_request.json
Search Operators
Field Operators
=
- Equals
!=
- Not equals
<
- Less than
>
- Greater than
<=
- Less than or equal
>=
- Greater than or equal
IN
- In list
NIN
- Not in list
~
- Contains (for strings)
!~
- Does not contain
Query Operators
AND
- All conditions must match
OR
- Any condition can match
Example Complex Search
Write to
/tmp/intercom_request.json
:
{
"query"
:
{
"operator"
:
"AND"
,
"value"
:
[
{
"field"
:
"role"
,
"operator"
:
"="
,
"value"
:
"user"
}
,
{
"field"
:
"created_at"
,
"operator"
:
">"
,
"value"
:
1609459200
}
,
{
"field"
:
"custom_attributes.plan"
,
"operator"
:
"IN"
,
"value"
:
[
"premium"
,
"enterprise"
]
}
]
}
,
"pagination"
:
{
"per_page"
:
50
}
}
Then run:
/tmp/intercom-curl
-X
POST
"https://api.intercom.io/contacts/search"
-d
@/tmp/intercom_request.json
|
jq
'.data[] | {id, email, name}'
Rate Limits
Private Apps
10,000 API calls per minute
Public Apps
10,000 API calls per minute
Workspace Limit
25,000 API calls per minute (combined)
When rate limited, API returns
429 Too Many Requests
.
Rate Limit Headers
:
X-RateLimit-Limit
Requests per minute allowed
X-RateLimit-Remaining
Remaining requests in current window
X-RateLimit-Reset
Unix timestamp when limit resets
Guidelines
Always include required headers
All requests should have
Authorization
,
Accept: application/json
, and
Intercom-Version: 2.14
headers
Use correct HTTP methods
:
GET
for retrieving data
POST
for creating resources and searches
PATCH
for updating resources (not PUT)
DELETE
for removing resources
Handle rate limits
Monitor
X-RateLimit-Remaining
and implement exponential backoff
Wait after creating resources
Newly created contacts may need a few seconds before they can be updated or searched
Use search wisely
Search endpoints are powerful but count toward rate limits
Pagination
Use cursor-based pagination for large datasets
Test with small datasets
Verify your queries work before scaling up
Secure tokens
Never expose access tokens in public repositories or logs
Use filters
Narrow search results with filters to reduce API calls
Conversation states
Valid states are
open
,
closed
,
snoozed
Custom attributes
Define custom fields in Intercom UI before using in API
Check workspace ID
Your workspace ID is included in contact responses for verification API Reference Main Documentation: https://developers.intercom.com/docs API Reference: https://developers.intercom.com/docs/references/rest-api/api-intercom-com/ Authentication: https://developers.intercom.com/docs/build-an-integration/learn-more/authentication/ Rate Limiting: https://developers.intercom.com/docs/references/rest-api/errors/rate-limiting/ Contacts API: https://developers.intercom.com/docs/references/rest-api/api-intercom-com/contacts/ Conversations API: https://developers.intercom.com/docs/references/rest-api/api-intercom-com/conversations/ Developer Hub: https://app.intercom.com/a/apps/_/developer-hub
← 返回排行榜