Aller au contenu principal

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
Lien direct vers Installer l'adaptateur

Installez l'adaptateur Photon iMessage :

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

Configuration de l'Agent
Lien direct vers Configuration de l'Agent

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

src/mastra/agents/imessage-agent.ts
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 :

src/mastra/index.ts
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
Lien direct vers Configuration de l'adaptateur

Suivez la documentation de l'adaptateur Photon 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 et utilisez les identifiants du projet :

.env
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 :

.env
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
Lien direct vers 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 :

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

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

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

Enregistrez cette URL dans le tableau de bord Photon, 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 install @chat-adapter/state-redis

createRedisState() lit la variable d'environnement REDIS_URL :

src/mastra/agents/imessage-agent.ts
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.

Écouteur de passerelle
Lien direct vers É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 :

src/mastra/agents/imessage-agent.ts
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.

On this page