Connect Intercom to WhatsApp

Unlike most APIs in this series where you search via GET query parameters, Intercom's contact search endpoint is a POST request with a structured JSON body. Your External API Request step must be set to POST, not GET, even though you are only reading data. This is the most common mistake when first setting up this integration.

The Intercom access token gives full read and write access to your workspace. Store it securely in WA.Expert's step configuration and do not share it. If compromised, regenerate it from the same Developer Hub page.

Intercom REST API reference: developers.intercom.com/docs

Without Intercom-Version: 2.11, Intercom defaults to the version your Developer Hub app was originally registered on, which may be older and have different field names. Always include this header.

Intercom supports AND and OR operators at the top level of the query value array for multi-field searches.

{
  "type": "list",
  "data": [
    {
      "type": "contact",
      "id": "64a1b2c3d4e5f6a7b8c9d0e1",
      "workspace_id": "abc123",
      "external_id": "usr_001",
      "role": "user",
      "email": "priya@example.com",
      "name": "Priya Sharma",
      "phone": "+919820000001",
      "avatar": null,
      "created_at": 1718870400,
      "updated_at": 1719216000,
      "last_seen_at": 1719216000,
      "unsubscribed_from_emails": false,
      "custom_attributes": {
        "plan": "pro",
        "account_value": "125000"
      }
    }
  ],
  "total_count": 1,
  "pages": {
    "type": "pages",
    "page": 1,
    "per_page": 1,
    "total_pages": 1
  }
}

Map: data[0].id, data[0].name, data[0].email, data[0].role
     data[0].custom_attributes.plan (if you store plan in Intercom)

Intercom wraps search results in a 'list' object with a 'data' array. Map as data[0].name, data[0].email. If total_count is 0 or data is empty, the contact was not found. The role field tells you whether this is a 'user' (known customer) or 'lead' (anonymous visitor).

custom_attributes contains any fields you have added to your Intercom contacts: plan, account value, company, region, or any other data you track. The key names match what you set in Intercom.

If the customer messaged you first within the last 24 hours, your reply is a free service conversation. For proactive outbound messages using Intercom data, use an approved Utility or Marketing template.

GET https://api.intercom.io/contacts/64a1b2c3d4e5f6a7b8c9d0e1/conversations
Authorization: Bearer YOUR_INTERCOM_ACCESS_TOKEN
Intercom-Version: 2.11

Response (abbreviated):
{
  "type": "list",
  "conversations": [
    {
      "id": "483",
      "title": "Need help with my order",
      "state": "open",
      "created_at": 1719000000,
      "updated_at": 1719200000
    }
  ],
  "total_count": 2
}

Map: conversations[0].id, conversations[0].title, conversations[0].state
state can be: open, closed, snoozed

Customer messages: "Can someone look into my account?"

Bot asks: "Please share the email on your account."
Customer: priya@example.com
Stored as {{customer_email}}.

External API Request step (POST):
URL: https://api.intercom.io/contacts/search
Headers:
  Authorization: Bearer eyJhbGciOi...
  Content-Type: application/json
  Intercom-Version: 2.11
Body:
  {{"query": {{"field": "email", "operator": "=", "value": "{{customer_email}}"}}}}

Response mapped:
contact_id   = "64a1b2c3d4e5f6a7b8c9d0e1"
contact_name = "Priya Sharma"
contact_plan = "pro"
total_count  = "1"

Conditions: if total_count = 0 → "No account found for this email."

Bot replies (if found):
"Hi Priya Sharma, I can see your account.
Plan: Pro

Reply SUPPORT and a team member will pick this up,
or ORDERS to check your recent order status."