Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

7.2 KB
Raw Blame
---
title: Linq
description: Connect an eve agent to iMessage and SMS through Linq.
---

Use `linqChannel` to receive and reply to iMessage and SMS conversations through Linq.

Run `eve add channel/linq` to choose Vercel Connect or portable credentials. With Vercel Connect, eve signs you in and creates or links a Vercel project when needed. Then choose whether to create a managed Linq account and line or connect an existing account with its partner API token. eve fetches the phone numbers assigned to that account, and you select the numbers for the agent. eve configures the connector and webhook through Connect:

```ts title="agent/channels/linq.ts"
import { connectLinqCredentials } from "@vercel/connect/eve";
import { linqChannel } from "eve/channels/linq";

export default linqChannel({
  credentials: connectLinqCredentials("linq/my-agent"),
});
```

The default webhook route is `/eve/v1/linq`. The channel verifies forwarded webhooks with Vercel OIDC from the same project and environment by default, derives user auth from each message author, marks accepted messages as read, and continues the same eve session for every message in a Linq conversation. A new accepted message steers the active turn. Before answer output or local tool execution begins, steering can interrupt pending model generation. Executing tools finish first; after answer output starts, steering waits for the next committed workflow boundary. See [Overlapping messages](./overview#overlapping-messages).

Set `turnPolicy: "queue"` when every response should finish before Linq starts the next message.

Images and other files people send reach the agent as file parts. eve downloads each one from Linq's CDN and passes the bytes; a failed download, or a file over 25 MB, reaches the agent as a short note.

Customize inbound dispatch with `onMessage`. Return `null` to ignore a message, or return `title` alongside `auth` to set the title when the dispatch starts a run:

```ts
export default linqChannel({
  credentials: connectLinqCredentials("linq/my-agent"),
  onMessage(_ctx, message) {
    if (message.author.isBot) return null;
    return {
      auth: null,
      context: [`The sender is ${message.author.fullName}.`],
    };
  },
});
```

Set `route` to override the webhook path or `webhookVerifier` to use a different trusted-forwarder verifier. A verifier rejects a webhook by throwing or returning a falsy value such as `null` or `false`.

## Tapbacks

eve ignores tapbacks people send unless you pass `onTapback`. It receives the tapback and returns the same result as `onMessage`, or `null` to ignore it:

```ts title="agent/channels/linq.ts"
import { connectLinqCredentials } from "@vercel/connect/eve";
import { defaultLinqAuth, linqChannel } from "eve/channels/linq";

export default linqChannel({
  credentials: connectLinqCredentials("linq/my-agent"),
  onTapback(_ctx, tapback) {
    if (!tapback.added) return null;
    return { auth: defaultLinqAuth(tapback) };
  },
});
```

The agent reads an accepted tapback as a message in the form iMessage uses when it shows a tapback as text, such as `Tapback: Loved “See you at 7”` or `Tapback: Removed a like tapback from a message`. The quoted text appears when Linq can return the message the tapback is on. `tapback.tapback` is `love`, `like`, `dislike`, `laugh`, `emphasize`, or `question`, or the emoji itself for an emoji tapback. `tapback.messageId` and `tapback.author` identify the message and the person. An accepted tapback starts or steers a turn like any other message, following `turnPolicy`. The agent's own tapbacks never reach `onTapback`. `onTapback` runs instead of `onMessage` for tapbacks, so repeat any sender checks from `onMessage` there. Tapbacks arrive through the `reaction.added` and `reaction.removed` webhook events, which `eve add channel/linq` subscribes to.

To let the agent send tapbacks, export the channel's tapback tool from a file in `agent/tools/`. The file name becomes the tool name:

```ts title="agent/tools/tapback.ts"
import linq from "../channels/linq";

export default linq.tapbackTool();
```

The model calls it with a standard tapback, such as `{ "tapback": "love" }`, or any single emoji, such as `{ "tapback": "🎉" }`, and eve reacts to the latest message someone sent in the conversation. A standard tapback's own emoji, such as `👍`, sends that tapback. The model can send a tapback alongside a reply. To let a tapback be the whole answer, also add [`no_reply`](../concepts/built-in-tools#no_reply). The tool is never added on its own, and subagents don't receive it. In a session that didn't come through this channel, such as a web chat, or before anyone has sent a message, the call fails with an error the model reads.

### Answer approvals with a tapback

Return `answer` from `onTapback` to answer the input request eve posted in the message the tapback is on. A [tool approval](/docs/human-in-the-loop#approvals) offers the options `approve` and `cancel`, so a like or dislike on the approval prompt can approve or cancel it:

```ts title="agent/channels/linq.ts"
import { connectLinqCredentials } from "@vercel/connect/eve";
import { defaultLinqAuth, linqChannel } from "eve/channels/linq";

export default linqChannel({
  credentials: connectLinqCredentials("linq/my-agent"),
  onTapback(_ctx, tapback) {
    if (!tapback.added) return null;
    const auth = defaultLinqAuth(tapback);
    if (tapback.tapback === "like") return { auth, answer: "approve" };
    if (tapback.tapback === "dislike") return { auth, answer: "cancel" };
    return { auth };
  },
});
```

`answer` settles only the request posted in that message, and only while it is still waiting and offers that option. A tapback on any other message, or on a prompt that was already answered, reaches the agent as an ordinary tapback, such as `Tapback: Liked “Got it”`. The approval's response policy still decides whether the person who sent the tapback may answer. For a [question](/docs/human-in-the-loop#questions), return one of its option ids. To replace the text the agent receives for a tapback, return `message`. Don't set `message` to an option's id, label, or number: eve reads that text like a typed reply, which answers the first waiting approval no matter which message the tapback is on.

## Other hosts

For a host without Vercel Connect, choose **Use portable credentials** during `eve add channel/linq`. eve writes `LINQ_API_KEY` and `LINQ_WEBHOOK_SECRET` to `.env.local`.

After deploying the agent:

1. Create a Linq webhook for your public `https://…/eve/v1/linq` URL with `message.received`, `reaction.added`, and `reaction.removed` events.
2. Set `LINQ_API_KEY` and `LINQ_WEBHOOK_SECRET` in the host's encrypted environment variables.

To configure the channel by hand, pass the API key and webhook signing secret:

```ts title="agent/channels/linq.ts"
import { linqChannel } from "eve/channels/linq";

export default linqChannel({
  credentials: {
    apiKey: process.env.LINQ_API_KEY!,
    signingSecret: process.env.LINQ_WEBHOOK_SECRET!,
  },
});
```

For direct Linq webhooks, pass `signingSecret`. A supplied `webhookVerifier` takes precedence over it.

## What to read next

- [Channels overview](./overview): the channel contract and every built-in channel
- [Auth & route protection](../guides/auth-and-route-protection): authenticating inbound traffic