Photon for Dify

Send and read messages on iMessage, SMS, WhatsApp, WhatsApp Business, email, and Telegram from Dify workflows, chatflows, and agents, through Photon's messaging API (API reference).

Photon calls a conversation a space. Each space belongs to one platform (, , , , , or ), and a message sent into a space goes out on that platform, so the same tools work for every channel.

Tools

Tool	What it does	Photon API
	Sends text () or JPEG, PNG, GIF, or WebP images of up to 10 MB each () into an existing space.	Upload attachment, Send a Message
	Lists spaces, optionally for one platform or participant.	List Spaces
	Returns the space for the given users on one platform, creating it if needed.	Create or get a Space
	Lists messages by platform, direction, and creation time, or one space's messages.	List Messages
	Returns one message with its sender, content, and delivery status.	Get a Message
	Returns one user's handle, and whether it is an agent (a line or account Photon manages) or a person.	Get an User
	Returns the user for a phone number or email address on one platform, creating it if Photon does not know it yet.	Create or get a User
	Returns an attachment's metadata, and its file as a Dify file.	Get attachment, Download attachment

Setup

In your Photon project, connect the channels you will use (Messaging). The plugin does not connect channels.
Create an Account Service Key () or a Project API key (), and copy the project ID () (Set up your project).
Install Photon from the Dify Marketplace, then authorize it under Tools > Photon:

Credential	Required	Value
	Yes	The raw key, without .
	Yes	The project ID.

On self-hosted Dify, set (or ) to a Dify API address the plugin can reach; otherwise the plugin cannot download the images it is asked to send.

Usage

Send text, or images with optional text:

Several images, or images with text, are sent as one message: the text first, then the images in order. Each image is uploaded to Photon before the message.
is the project's agent user in the space: the of a message received in it, or the of one sent from it. tells agents () from people; this project's dedicated lines have .
(reply) and are optional.
and are required and have no default. is , which sends the text as written, or , which is CommonMark with GFM tables and strikethrough. Photon renders Markdown with the channel's own formatting where the channel has it, for example on Telegram, and as readable plain text elsewhere; it rejects HTML in Markdown.
Photon decides what each channel accepts. When it rejects a send, the error keeps Photon's status, code and reason, for example . Photon's problem catalog lists the codes.
Sending is asynchronous: the result is usually . Call later: confirms delivery, means the channel took the message without confirming delivery ( says why), and carries .
Reuse the same to retry a send safely. If you omit it, the plugin generates one and returns it in the result, and in the error if the send fails.

To start a conversation with someone new, get their user with , then a space with , and send into that space:

must include one of the project's agents, the one that will send: the of a message received on that line, or the user returns for the line's own number (). On iMessage, put the agent first. A new iMessage space needs one of the project's dedicated lines; a shared line only returns the existing direct space with a person assigned to the project on that line.
A known handle returns its existing user, and direct spaces and SMS groups with the same participants return the existing space. On email, each new starts a new thread.

Lists return Photon's page: , and when there are more. To get the next page, pass it as with the same filters. To list one space's messages, pass with , the project's agent user in that space; Photon then does not accept , or .

Results are Photon's objects as the API returns them. A message has , , , , when Photon records it, , , , , and or when they apply; a text message's text is . Each top-level field of a result is also a named output variable.

returns the file as a Dify file output for workflows, for example for a vision model; in Agent apps the model cannot see the file. Files over 50 MB, Dify's default limit for plugin files, are not downloaded.

Connection requirements

The plugin makes HTTPS requests to Photon at , and downloads the images to send from the URLs Dify provides for them.

Limitations

Received messages start workflows through the separate Photon Trigger plugin, in of this repository. Delivery status webhooks are not covered.
Photon does not create users or spaces on Telegram (); a Telegram conversation starts when the person messages the bot.
Sending covers text and images. Reading returns every content type.
Classic Agent apps cannot pass files to tools, so they send text only; workflows and the newer Agent can send images.

Privacy

See PRIVACY.md.

Development

Source: photon-hq/dify. With Python 3.12:

The tests mock Photon and Dify's file downloads and never send messages.

Every merge to publishes a GitHub prerelease with a staging build and the production candidate. The production release is published by running the Promote to production workflow.

License

MIT