> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jengolabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Intercom

> Let your Grio CX agent answer customers inside your own Intercom, as a teammate.

Your Grio CX agent joins your Intercom as a teammate. It replies to the conversations you send it, hands over to your team when it can't help, and closes conversations once the customer is happy. Your inbox, Messenger, workflows and reports stay exactly as they are.

```mermaid theme={null}
sequenceDiagram
  participant C as Customer
  participant I as Your Intercom
  participant G as Grio CX
  C->>I: Writes in the Messenger
  I->>I: Your workflow assigns it to the Grio teammate
  I->>G: Lets Grio know
  G->>I: Replies as the Grio teammate
  Note over G,I: Can't help? Adds a note for your team and assigns it to them
  Note over G,I: Solved? Closes the conversation
```

<Info>
  Setup takes about **20 minutes**. You'll go back and forth between Intercom and Grio three times: create things in Intercom, connect them in Grio, then switch notifications on in Intercom.
</Info>

## Before you start

<CardGroup cols={3}>
  <Card title="Intercom admin" icon="user-shield">
    You need admin rights to create an app, a teammate and a workflow.
  </Card>

  <Card title="One Intercom seat" icon="chair">
    For the Grio teammate. It must have **Inbox** access to reply.
  </Card>

  <Card title="A Grio CX agent" icon="robot">
    Already set up with your knowledge base. Your Grio contact can help.
  </Card>
</CardGroup>

<Tip>
  Keep two browser tabs open side by side: one on Intercom, one on Grio. You'll copy values from one to the other.
</Tip>

## Part 1 — In Intercom

<Steps>
  <Step title="Add the Grio teammate">
    In Intercom, go to **Settings** → **Teammates** and invite a new teammate.

    * **Name**: what customers will see on Grio's replies, for example **Grio CX** or your support brand's name.
    * **Email**: an address your company controls, for example `grio@yourcompany.com`.
    * **Seat**: give it a seat with **Inbox** access.

    Accept the invitation from that mailbox so the teammate becomes active.

    <Warning>
      Without an Inbox seat, Intercom refuses every reply Grio tries to send.
    </Warning>
  </Step>

  <Step title="Create a private app">
    Go to **Settings** → **Integrations** → **Developer Hub** and click **New app**.

    * **App name**: `Grio CX`
    * **Workspace**: your company's workspace

    The app stays private to your workspace. Nobody outside your company can install it.
  </Step>

  <Step title="Give the app its permissions">
    In your new app, open **Authentication** → **Edit** and tick:

    * Read and write conversations
    * Read and write tags
    * Read admins
    * Read users and companies
    * Read and list articles (lets Grio answer from your Help Center)

    Click **Save**.
  </Step>

  <Step title="Copy two values">
    Keep these for Part 2:

    | Value | Where to find it |
    | - | - |
    | **Access token** | Your app → **Authentication** |
    | **Client secret** | Your app → **Basic information** |

    <Warning>
      Both values open your Intercom. Paste them only into Grio. Never send them by email or chat.
    </Warning>
  </Step>
</Steps>

## Part 2 — In Grio

<Steps>
  <Step title="Open your agent's connections">
    In Grio, go to **Agents**, open the agent that will answer in Intercom, then click **Add connection** → **Helpdesks** → **Intercom**.
  </Step>

  <Step title="Connect">
    * **Region**: where your Intercom workspace is hosted (**Europe**, **United States** or **Australia**). If unsure, look at your Intercom address: `app.eu.intercom.com` is Europe, `app.au.intercom.com` is Australia, otherwise United States.
    * **Access token** and **Client secret**: paste the two values from Part 1.

    Click **Connect**. Grio checks them with Intercom straight away.
  </Step>

  <Step title="Choose who writes and who takes over">
    * **Writes as**: the teammate you created in Part 1.
    * **Hands over to**: the team (or person) that takes conversations Grio can't handle.
    * **Answer from your Help Center**: leave it on to let Grio use your Intercom articles.
    * **Close when resolved**: leave it on to let Grio close conversations once the customer confirms.

    Click **Continue**. Grio now shows a **Webhook URL**. Copy it.
  </Step>
</Steps>

## Part 3 — Back in Intercom

<Steps>
  <Step title="Let Intercom notify Grio">
    In **Developer Hub**, open your app → **Webhooks**.

    1. Paste the **Webhook URL** from Grio.
    2. Tick these six topics:

    ```text theme={null}
    conversation.admin.assigned
    conversation.user.created
    conversation.user.replied
    conversation.admin.replied
    conversation.admin.noted
    conversation.admin.closed
    ```

    3. Click **Save**.

    <Check>
      Within a minute, Grio shows **Intercom reached the agent**.
    </Check>
  </Step>

  <Step title="Send conversations to Grio">
    Go to **Workflows** and create a workflow that **assigns** conversations to the Grio teammate. For example: *when a customer opens a new conversation → assign to Grio CX*.

    <Tip>
      Grio only answers conversations assigned to its teammate, so the workflow decides how much it handles. Start small (one channel, one language or one audience), check the answers for a few days, then widen.
    </Tip>
  </Step>

  <Step title="Try it">
    Open your Messenger as a customer and ask something your Help Center answers. Grio replies within about 15 seconds.

    Then ask to talk to a person: Grio adds a note for your team and assigns the conversation to them.
  </Step>
</Steps>

## Day to day

| You want to | Do this in Intercom |
| - | - |
| Take over a conversation | Reply, or assign it to yourself. Grio stops answering it. |
| Give it back to Grio | Assign it to the Grio teammate. |
| Pause Grio everywhere | Turn off the workflow from Part 3. |
| Follow up later on a closed conversation | In Grio, open the conversation and click **Follow up**. Grio reopens it in Intercom and writes to the customer. |

Every conversation Grio handles also appears in Grio, read-only, with its summary, sentiment and the agent's reasoning. Replies always happen in Intercom.

## If something doesn't work

<AccordionGroup>
  <Accordion title="Grio never replies">
    Check three things:

    1. The six webhook topics are ticked and the Webhook URL is saved (Part 3, step 1).
    2. The conversation is assigned to the Grio teammate (Part 3, step 2).
    3. The Grio teammate has a seat with **Inbox** access (Part 1, step 1).
  </Accordion>

  <Accordion title="“This admin does not have Inbox access”">
    Give the Grio teammate a seat with **Inbox** access in **Settings** → **Teammates**.
  </Accordion>

  <Accordion title="Connect fails in Grio">
    Make sure the **Region** matches your Intercom workspace and that the access token was copied in full. If Grio says the token can't read your teammates, add **Read admins** to the app's permissions (Part 1, step 3).
  </Accordion>

  <Accordion title="Grio stays on “Waiting for Intercom's first notification”">
    Send a message in the Messenger on a conversation assigned to Grio. The first notification arrives with it.
  </Accordion>

  <Accordion title="Grio stopped working after a while">
    If the access token was revoked or the app uninstalled, Grio pauses the connection and asks for new credentials. Create a new access token (Part 1, step 4) and paste it in **Add connection** → **Intercom**.
  </Accordion>
</AccordionGroup>

Need a hand during setup? Contact your Grio representative.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.