Photon Trigger for Dify

Start Dify workflows when a message arrives over iMessage, SMS, WhatsApp, WhatsApp Business, email, or Telegram, through Photon's messaging API (API reference).

Photon calls a conversation a space. Each space belongs to one platform, and the project's own phone numbers, bots, and email accounts are its agent users. When the project receives a message, Photon delivers a signed webhook, and this plugin starts the workflows that use its event. To reply, use the Photon plugin's .

Events

Setup

1. In your Photon project, connect the channels you will use (Messaging). The plugin does not connect channels.
2. Create an Account Service Key () or a Project API key () that can manage the project's webhook destinations, and copy the project ID () (Set up your project).
3. Install Photon Trigger, add its Message received event as a workflow's start node, and create a subscription with:

Creating the subscription creates a Photon webhook destination for the subscription's Dify endpoint (Create webhook destination), subscribed to , and Dify keeps the destination's signing secret with the subscription. Deleting the subscription deletes the destination (Delete webhook destination).

Photon delivers only to public HTTPS URLs. On self-hosted Dify, set to the public HTTPS address of your Dify API before creating the subscription, because Dify builds the endpoint from it.

Usage

The event's variables are Photon's message as the webhook carries it: , , , , , , , , , and when the message is a reply. says what arrived; a text message's text is , and an attachment's ID is , for the Photon plugin's . Besides text and attachments, can carry other content, such as a reaction (), an edit (), a deletion (), a read receipt (), or a poll (), and these start the workflow too; to answer only text, branch on .

To reply in the same space, pass these to the Photon plugin's :

is the project's agent user that received the message, so the reply comes from the same number, bot, or email account. Photon delivers a message again when a delivery times out or fails; a key made from the message's keeps a repeated delivery from sending a second reply.

The event has three optional parameters, set on the start node: Platforms (start only for the selected platforms; none selected means all), Text contains (case-insensitive), and Text regex. A message that does not match is skipped and starts nothing; with Text contains set, a message without text is skipped.

Every delivery is checked against Photon's signature before a workflow starts: the Standard Webhooks HMAC-SHA256 signature over the delivery's ID, timestamp, and body, with the timestamp within 5 minutes. Deliveries that fail the check start nothing.

Connection requirements

The plugin makes HTTPS requests to Photon at to check the key (List webhook destinations) and to create and delete the webhook destination (Create webhook destination, Delete webhook destination). Photon sends deliveries to the subscription's Dify endpoint.

Limitations

• Only received messages start workflows; delivery status and other Photon events do not.
• A subscription receives every of the project. To handle only some, use the event's parameters, or branch on in the workflow to handle one line.
• The subscription keeps the signing secret Photon returned when it was created. If the destination's secret is rotated in Photon, deliveries fail the check once the old secret expires; delete and recreate the subscription instead.
• If Photon cannot be reached when a subscription is deleted, Dify still deletes the subscription, and its webhook destination stays in Photon; delete it there.

Privacy

See PRIVACY.md.

Development

Source: photon-hq/dify, in . With Python 3.12, from :

The tests mock Photon and never create destinations.

License

MIT