# Chat

## What this is

Hookshot™ Chat lets you talk directly to a Protege or to the built-in Hookshot responder inside Slack threads and Asana task comments by mentioning `@hookshot`.

## When to use it

Use Chat when you want to:

* Ask a question or give an instruction inside an existing Slack thread or Asana task
* Get a response from Hookshot without creating a dedicated Protege
* Continue a conversation where the work is already happening

## What you need first

* A connected Slack or Asana integration with chat enabled
* A team-scoped chat connection in the integration settings

## Steps

### 1. Enable chat on an integration

For Slack or Asana:

1. Open **Integrations**
2. Select the integration
3. Enable chat in the integration detail view
4. Confirm the chat connection is team-scoped and active

Chat connections are always team-scoped. They cannot be personal connections.

### 2. Invoke Hookshot in a conversation

In Slack or Asana, mention Hookshot to start a conversation:

* **Slack**: Use `@hookshot`, `@hookshotdev`, or `@composio` in a channel where the Slack bot is present
* **Asana**: Include `@hookshot`, `@hookshotdev`, or `@composio` in a task comment

{% hint style="info" %}
Chat requires an explicit mention. Hookshot does not passively listen to all messages — it only responds when invoked.
{% endhint %}

### 3. Understand System Chat vs Protege Chat

Hookshot routes chat conversations to one of two targets:

| Target           | When it applies                                  | Behavior                                                                |
| ---------------- | ------------------------------------------------ | ----------------------------------------------------------------------- |
| **System Chat**  | No specific Protege is bound to the conversation | Built-in Hookshot responder handles the message using standard AI tools |
| **Protege Chat** | A Protege is bound to the conversation           | The Protege's skill, tools, and configuration drive the response        |

System Chat requires no setup beyond enabling chat on the integration. It is always available when chat is enabled.

### 4. Continue a conversation

After the first mention, subsequent messages in the same thread or task continue the conversation with the same target. You do not need to mention `@hookshot` again in follow-up messages within the same thread.

For Asana, follow-up comments that do not mention Hookshot are still processed if they are in a task where an active conversation binding exists.

### 5. Watch for in-progress indicators

When Hookshot is processing a chat message, you will see:

* **Slack**: An `:eyes:` emoji reaction appears on the triggering message while the response is being generated
* **Asana**: A temporary comment reading "Hookshot is working on this..." appears and is automatically deleted once the response is posted

### 6. Review the response

The response appears as a reply in the same Slack thread or as a comment on the same Asana task. If the Protege uses a tool to post the message directly, the auto-reply is skipped to avoid duplicate posts.

You can verify chat activity in:

* **Event Feed**: Shows the inbound chat event
* **Audit**: Shows the chat run with tool usage and outcome

## Chat configuration

Each integration with chat support has per-team configuration:

* **Enabled/disabled**: Turn chat on or off for the team
* **Coverage mode**: How Hookshot decides which conversations to monitor (currently `mention_anywhere`)
* **Response mode**: How Hookshot replies (currently `reply_in_thread`)

For Asana, you can select specific projects or portfolios for chat coverage. For Slack, confirm the correct channel boundary.

## How chat routing works

1. A user mentions `@hookshot` in Slack or Asana
2. Hookshot receives the event via the connected integration
3. The chat routing layer checks if an existing conversation binding exists for this thread or task
4. If a binding exists: the conversation continues with the bound target (System Chat or a specific Protege)
5. If no binding exists: a new conversation is created with System Chat or the first eligible Protege
6. The target Protege runs, and the response is posted back to the thread or task

## How to verify

* Chat is enabled on the integration detail page
* The chat connection shows as active and team-scoped
* Mentioning `@hookshot` in the target channel or task produces a response
* The response appears in the same thread or task
* The run appears in Audit with `chat` execution mode

## Common failures

* Enabling chat but not confirming the chat connection is active
* Expecting Hookshot to respond without an explicit `@hookshot` mention
* Using a personal connection instead of a team connection for chat (chat connections must be team-scoped)
* Mentioning Hookshot in a channel or project that is outside the configured coverage
* Checking only Slack or Asana for the response without confirming the run completed in Audit

## Next step

* [Integrations Overview](/integrations.md)
* [Slack](/integrations/slack.md)
* [Asana](/integrations/asana.md)
* [Create a Protege](/create-a-protege.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.tryprotege.com/create-a-protege/chat.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.