CONNECT APP
Build with Element
Secure collaboration and messaging
Communication
- API key
MCP
Give your agent Element tools
Every Element action is exposed as an MCP tool on Pipedream's remote server. Point a client at it with your end user's ID and Connect resolves that user's Element account for each tool call — you store no tokens.
// accessToken: mint a short-lived token with the Connect SDK — see the MCP guide
const transport = new StreamableHTTPClientTransport(
new URL("https://remote.mcp.pipedream.net/v3"),
{
requestInit: {
headers: {
Authorization: `Bearer ${accessToken}`,
"x-pd-project-id": "{project_id}",
"x-pd-environment": "production",
"x-pd-external-user-id": "{external_user_id}", // any stable ID for this user in your system
"x-pd-app-slug": "element",
},
},
},
)
const mcp = new Client({ name: "my-agent", version: "1.0.0" })
await mcp.connect(transport)
const { tools } = await mcp.listTools()
// e.g. run Ban User:
const result = await mcp.callTool({
name: "element-ban-user",
arguments: {
roomId: "Room ID",
userId: "User ID",
},
})# access_token: mint a short-lived token with the Connect SDK — see the MCP guide
headers = {
"Authorization": f"Bearer {access_token}",
"x-pd-project-id": "{project_id}",
"x-pd-environment": "production",
"x-pd-external-user-id": "{external_user_id}", # any stable ID for this user in your system
"x-pd-app-slug": "element",
}
async with streamablehttp_client("https://remote.mcp.pipedream.net/v3", headers=headers) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
# e.g. run Ban User:
result = await session.call_tool("element-ban-user", {
"roomId": "Room ID",
"userId": "User ID",
})API PROXY
Call the Element API directly
For an endpoint with no pre-built tool, the Connect proxy forwards your request to the Element API with the connected user's credentials attached. You store no tokens and write no refresh logic.
const resp = await pd.proxy.get({
externalUserId: "{external_user_id}", // any stable ID for this user in your system
accountId: "apn_xxxxxxx",
url: "https://api.example.com/v1/me",
})
// Any allowed Element endpoint works here. Pipedream attaches the
// connected account's credentials to the outgoing request.# The path segment is the target URL, URL-safe base64 encoded:
# https://api.example.com/v1/me
curl "https://api.pipedream.com/v1/connect/{project_id}/proxy/aHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdjEvbWU?external_user_id={external_user_id}&account_id=apn_xxxxxxx" \
-H "Authorization: Bearer {access_token}" \
-H "x-pd-environment: production"SDK
Run Element actions from your backend
Connect a user's Element account once, then run Ban User on their behalf from your own code — TypeScript, Python, or plain HTTP.
import { PipedreamClient } from "@pipedream/sdk"
const pd = new PipedreamClient({
projectId: process.env.PIPEDREAM_PROJECT_ID!,
clientId: process.env.PIPEDREAM_CLIENT_ID!,
clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
projectEnvironment: "production",
})
const result = await pd.actions.run({
id: "element-ban-user",
externalUserId: "{external_user_id}", // any stable ID for this user in your system
configuredProps: {
element: { authProvisionId: "apn_xxxxxxx" },
roomId: "Room ID",
userId: "User ID",
},
})from pipedream import Pipedream
pd = Pipedream(
client_id="{oauth_client_id}",
client_secret="{oauth_client_secret}",
project_id="{project_id}",
project_environment="production",
)
result = pd.actions.run(
id="element-ban-user",
external_user_id="{external_user_id}", # any stable ID for this user in your system
configured_props={
"element": {"authProvisionId": "apn_xxxxxxx"},
"roomId": "Room ID",
"userId": "User ID",
},
)curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
-H "Content-Type: application/json" \
-H "X-PD-Environment: production" \
-H "Authorization: Bearer {access_token}" \
-d '{
"external_user_id": "{external_user_id}",
"id": "element-ban-user",
"configured_props": {
"element": { "authProvisionId": "apn_xxxxxxx" },
"roomId": "Room ID",
"userId": "User ID"
}
}'TOOLS
Element actions
On-demand operations your product or agent can configure and run on behalf of a connected user.
-
Ban User
actionBan a user from a room, also kicking them if they are currently joined. A banned user cannot rejoin or be invited back until the ban is lifted with Unban User — use Kick User instead to remove someone without blocking their return. The connected account must be in the room with a power level high enough to ban, otherwise the API returnsM_FORBIDDEN. Use List Rooms to find the room ID. See the documentationWritev0.0.2 -
Create Room
actionCreate a new room, optionally inviting other users to it right away. Returns the new room's ID, which can be passed into Send Message or Invite User. SetRoom Alias Nameto give the room a memorable local alias (e.g.thepubbecomes#thepub:matrix.orgon matrix.org). If you omitPreset,Visibilityalso picks join rules —publiccreates an openly-joinable room. See the documentationWritev0.0.2 -
Invite User
actionInvite a user to an existing room. The connected account must already be joined to the room and have permission to invite. Optionally include aReason, which is stored on the membership event. See the documentationWritev0.0.2 -
Kick User
actionRemove a user from a room without banning them. A kicked user can be invited back with Invite User, and can rejoin on their own if the room's join rules allow it — use Ban User instead to also block their return. The connected account must be in the room with a power level high enough to kick, otherwise the API returnsM_FORBIDDEN; the same error is returned if the target user is not currently in the room. Use List Rooms to find the room ID. See the documentationWritev0.0.2 -
Leave Room
actionLeave a room the connected account has joined, or reject a pending invite to it. After leaving, the account stops receiving new events in the room; rejoining an invite-only room requires a fresh invite, so treat this as hard to undo. Use List Rooms to find the room ID. See the documentationWritev0.0.2 -
List Rooms
actionList the Matrix rooms the connected account has joined. The Matrix API only returns room IDs from this endpoint (no name or topic) — pass a returned ID directly into Send Message or Invite User. Because the IDs are opaque, prefer Resolve Room Alias when you know the room by an alias such as#engineering:matrix.org. See the documentationRead-onlyv0.0.2 -
Resolve Room Alias
actionLook up the room ID that a human-readable room alias points to, e.g.#engineering:matrix.org. Every other action in this app takes a room ID (!OGEhHVWSdvArJzumhm:matrix.org) and rejects aliases, so use this first whenever you only know the alias. Aliases can be re-pointed to a different room over time, so always trust the returnedroom_idrather than assuming an alias still maps to the room you expect. Returns the room ID and the servers that know the alias. See the documentationRead-onlyv0.0.2 -
Send Message
actionSend a text message to a room. The room must be one the connected account has already joined, and must be identified by room ID rather than alias — use List Rooms to find it. Returns theevent_idof the sent message. See the documentationWritev0.0.2 -
Unban User
actionLift a ban on a user in a room, reversing Ban User. Unbanning does not put the user back in the room — it only allows them to be invited again, and to rejoin if the room's join rules would otherwise let them. The connected account must have a power level high enough to unban, otherwise the API returnsM_FORBIDDEN. Use List Rooms to find the room ID. See the documentationWritev0.0.2
EVENTS
Element triggers
Event sources your backend can deploy for users and receive through a webhook.
No Element triggers are available yet.
- App slug
- element
- Authentication
- API key
- Categories
- Communication
- Actions
- 9
- Triggers
- 0
- API proxy
- Available