> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# iMessage

Les canaux iMessage permettent à un Agent Mastra de recevoir des messages directs et des messages de groupe depuis iMessage. Mastra prend en charge le raccordement de l'Agent, la route de webhook et l'écouteur de passerelle ; la documentation de l'adaptateur Photon iMessage couvre l'attribution des numéros, les identifiants et l'enregistrement du webhook.

## Installer l'adaptateur

Installez l'adaptateur Photon iMessage :

**npm**:

```bash
npm install @photon-ai/chat-adapter-imessage
```

**pnpm**:

```bash
pnpm add @photon-ai/chat-adapter-imessage
```

**Yarn**:

```bash
yarn add @photon-ai/chat-adapter-imessage
```

**Bun**:

```bash
bun add @photon-ai/chat-adapter-imessage
```

## Configuration de l'Agent

Ajoutez `createiMessageAdapter()` à l'objet `channels.adapters` de l'Agent :

```typescript
import { Agent } from '@mastra/core/agent'
import { createiMessageAdapter } from '@photon-ai/chat-adapter-imessage'

export const imessageAgent = new Agent({
  id: 'imessage-agent',
  name: 'iMessage Agent',
  instructions: 'Answer questions and help with tasks over iMessage.',
  model: 'openai/gpt-5.6-sol',
  channels: {
    adapters: {
      imessage: {
        adapter: createiMessageAdapter(),
        toolDisplay: 'text',
      },
    },
    threadContext: { maxMessages: 0 },
  },
})
```

Enregistrez l'Agent dans l'instance Mastra :

```typescript
import { Mastra } from '@mastra/core'
import { imessageAgent } from './agents/imessage-agent'

export const mastra = new Mastra({
  agents: { imessageAgent },
})
```

Utilisez `imessage` comme clé d'adaptateur. Mastra déduit de cette clé le chemin du webhook et la valeur `platform` de `requestContext`.

`toolDisplay: 'text'` décrit les appels d'outils dans le message, car iMessage ne propose pas de cartes interactives pour les actions d'approbation et de refus. `threadContext: { maxMessages: 0 }` évite la recherche dans l'historique de la plateforme que Mastra effectue lorsqu'un Agent est mentionné pour la première fois dans une discussion de groupe, opération que l'adaptateur ne peut pas réaliser. Ces deux réglages remplacent des valeurs par défaut qui supposent la présence de fonctionnalités de plateforme absentes d'iMessage.

## Configuration de l'adaptateur

Suivez la [documentation de l'adaptateur Photon iMessage](https://github.com/photon-hq/vercel-chat-adapter-imessage) pour la configuration propre à iMessage, notamment l'attribution des numéros, les modes hébergé et auto-hébergé, ainsi que l'enregistrement du webhook. L'adaptateur choisit son mode d'après les variables d'environnement définies.

Pour le service hébergé, créez un projet sur [app.photon.codes](https://app.photon.codes) et utilisez les identifiants du projet :

```bash
IMESSAGE_PROJECT_ID=your-project-id
IMESSAGE_PROJECT_SECRET=your-project-secret
IMESSAGE_WEBHOOK_SECRET=your-webhook-signing-secret
```

Pour un serveur auto-hébergé, faites pointer l'adaptateur vers son adresse gRPC, écrite sous la forme `host:port`. L'adaptateur supprime tout schéma d'URL et ajoute `:443` à un nom d'hôte sans port :

```bash
IMESSAGE_SERVER_URL=imessage.example.com:443
IMESSAGE_API_KEY=your-server-token
IMESSAGE_PHONE=+15551234567
```

`IMESSAGE_PHONE` est facultatif et achemine les messages lorsqu'un serveur auto-hébergé dispose de plusieurs numéros. Vous pouvez également transmettre ces valeurs directement à `createiMessageAdapter()`, y compris une fonction `credentials` qui récupère l'identifiant et le secret du projet depuis un coffre de secrets lors de la première utilisation.

## URL du webhook

Mastra génère la route du webhook iMessage à partir de l'identifiant de l'Agent et de la clé de l'adaptateur :

```text
/api/agents/imessage-agent/channels/imessage/webhook
```

Utilisez l'URL publique de votre serveur Mastra comme URL de base :

```text
https://your-app.example.com/api/agents/imessage-agent/channels/imessage/webhook
```

Enregistrez cette URL dans le [tableau de bord Photon](https://app.photon.codes), puis définissez le secret de signature renvoyé comme `IMESSAGE_WEBHOOK_SECRET`. Ce secret n'est affiché qu'une fois lors de l'enregistrement. L'adaptateur vérifie la signature à chaque livraison et rejette les requêtes qui ne correspondent pas. Les webhooks sont disponibles uniquement en mode hébergé.

Photon retente les livraisons échouées avec un délai croissant et garantit au moins une livraison ; un même message peut donc arriver deux fois. Le SDK Chat élimine la répétition grâce à l'adaptateur d'état du canal, et la configuration par défaut de Mastra conserve ces clés de déduplication en mémoire. Cela suffit pour un serveur unique et persistant.

Une répétition peut néanmoins atteindre l'Agent après un redémarrage, ou dans un environnement serverless si la nouvelle tentative est acheminée vers une autre instance. Fournissez un adaptateur d'état partagé à `channels.state` afin que les clés de déduplication soient visibles partout. Installez-en un avec l'adaptateur :

**npm**:

```bash
npm install @chat-adapter/state-redis
```

**pnpm**:

```bash
pnpm add @chat-adapter/state-redis
```

**Yarn**:

```bash
yarn add @chat-adapter/state-redis
```

**Bun**:

```bash
bun add @chat-adapter/state-redis
```

`createRedisState()` lit la variable d'environnement `REDIS_URL` :

```typescript
import { createRedisState } from '@chat-adapter/state-redis'

channels: {
  adapters: {
    imessage: {
      adapter: createiMessageAdapter(),
      toolDisplay: 'text',
    },
  },
  threadContext: { maxMessages: 0 },
  state: createRedisState(),
},
```

Ce point est particulièrement important pour les outils ayant des effets de bord, car le traitement en double d'un même message est alors visible par l'utilisateur.

> **Remarque:** Photon livre uniquement vers des points de terminaison HTTPS publics. Il ne livre ni vers `http://`, ni vers des adresses privées comme `localhost`, ni au travers d'une redirection. Pour le développement local, utilisez un tunnel comme décrit dans la [présentation des canaux](https://mastra.zisheng.pro/fr/docs/capabilities/channels/overview).

## Écouteur de passerelle

L'adaptateur peut maintenir une connexion ouverte et diffuser les messages en temps réel au lieu de recevoir des webhooks. Cette méthode fonctionne aussi bien en mode hébergé qu'en mode auto-hébergé.

Mastra démarre cet écouteur pendant l'initialisation et le reconnecte si la connexion est interrompue ; aucun job cron ni route supplémentaire n'est donc nécessaire sur un serveur persistant. Définissez `gateway: false` dans la configuration de l'adaptateur pour le désactiver lorsque vous utilisez des webhooks :

```typescript
imessage: {
  adapter: createiMessageAdapter(),
  toolDisplay: 'text',
  gateway: false,
},
```

Sur les plateformes serverless, privilégiez les webhooks. Un écouteur de passerelle nécessite un processus qui reste actif. Consultez le [déploiement serverless](https://mastra.zisheng.pro/fr/docs/capabilities/channels/overview).

## Voir aussi

- [Présentation de Channels](https://mastra.zisheng.pro/fr/docs/capabilities/channels/overview)
- [Autres adaptateurs](https://mastra.zisheng.pro/fr/docs/capabilities/channels/other-adapters)