Embed App Actions

Embedded apps running inside Aptly can trigger UI interactions in the parent window — opening a card, starting a phone call, launching the email or SMS composer, creating an event, opening a conversation, and more — by posting a browser message. Aptly executes the action if your app has been granted that permission. This works alongside delegate token authentication. You can use one, the other, or both. For a compact, paste-friendly version of this page, see Aptly context for Claude.

Using the Aptly SDK (recommended)

If your app includes the Aptly SDK, use the named wrapper methods. They return a Promise<{ success: boolean, error?: string }>, handle the response listener for you, and time out after 3 seconds.

await aptly.openCardPane({ cardId: "abc123" });
await aptly.openCardView({ cardId: "abc123" });
await aptly.startDialer({ number: "+15551234567", name: "Jane Smith" });
await aptly.openEmailComposer({
  to: "[email protected]",
  subject: "Hello",
  content: "<p>Hi</p>"
});
await aptly.openSMSComposer({ to: "+15551234567", content: "Hi Jane" });
await aptly.createEvent({
  recipients: [{ value: "[email protected]", label: "Alex Tenant" }]
});
await aptly.createCard({ boardId: "board-uuid", fields: { name: "New Lead" } });
await aptly.createTask({
  title: "Follow up",
  dueAt: "2026-06-15T09:00:00.000Z",
  priority: "high"
});
await aptly.createContact({
  firstname: "Jane",
  lastname: "Smith",
  email: "[email protected]"
});
await aptly.navigateToContact({ contactId: "person123" });
await aptly.openConversation({ streamId: "stream123", title: "Jane Smith" });

// Generic escape hatch — useful when the action ID is dynamic
await aptly.action("start-dialer", { number: "+15551234567" });

// Check which actions are available at runtime before calling
console.log(aptly.actions); // e.g. ['start-dialer', 'create-card']

The SMS composer wrapper is spelled openSMSComposer (capital SMS).

Action reference at a glance

Action ID	SDK method	Required fields
`open-card-pane`	`aptly.openCardPane()`	`cardId`
`open-card-view`	`aptly.openCardView()`	`cardId`
`start-dialer`	`aptly.startDialer()`	`number`
`open-email-composer`	`aptly.openEmailComposer()`	none
`open-sms-composer`	`aptly.openSMSComposer()`	none
`create-event`	`aptly.createEvent()`	none
`create-card`	`aptly.createCard()`	`boardId`
`create-task`	`aptly.createTask()`	none
`create-contact`	`aptly.createContact()`	none
`navigate-to-contact`	`aptly.navigateToContact()`	`contactId`
`open-conversation`	`aptly.openConversation()`	`streamId`

“Required” means the action cannot do anything useful without the field. Aptly itself only validates streamId (see What success means).

Raw postMessage

If you are not using the SDK, post a message directly to the parent window. Aptly validates the permission and sends a response.

const APTLY_ORIGIN = "https://app.getaptly.com"; // use https://preview.getaptly.com for preview

window.parent.postMessage(
  {
    type: "aptly-action",
    action: "start-dialer",
    nonce: "any-unique-string", // optional; echoed back so you can match the response
    payload: { number: "+15551234567", name: "Jane Smith" }
  },
  APTLY_ORIGIN
);

Listen for the response:

const APTLY_ORIGINS = [
  "https://app.getaptly.com",
  "https://preview.getaptly.com"
];

window.addEventListener("message", (event) => {
  if (!APTLY_ORIGINS.includes(event.origin) || event.source !== window.parent)
    return;
  if (event.data?.type === "aptly-action-result") {
    const { action, success, error } = event.data;
    if (!success) console.warn(`Action ${action} failed: ${error}`);
  }
});

Aptly responds with { type: 'aptly-action-result', action, nonce, success: true } or { ..., success: false, error: 'Not permitted' }. The nonce you sent is echoed back on every response. The SDK wrappers add two error values of their own: error: 'timeout' if no response arrives within 3 seconds, and error: 'not-in-iframe' if the page is not running inside an Aptly embed.

What `success` means

success: true means Aptly dispatched the action, not that the user completed it or that every field was applied. The only payload check Aptly performs today is on open-conversation: a missing or non-string streamId returns success: false (with no error text). Every other action reports success: true once permitted, even if a field was ignored (see the per-action notes below).

Enabling actions for your app

Actions must be explicitly granted — nothing runs by default. An admin configures this in the settings for the specific embed. Marketplace app: In Global Admin → App Marketplace, open your app’s edit modal → Permissions tab → Embed Actions. When a user installs the app on a board, these permissions are copied to that board tab and can be adjusted in board settings. Custom board tab: In Board Settings → your tab → edit → Allowed Actions. Dashboard widget: In Dashboard → add or edit app → Embed Actions.

Available actions

`open-card-pane`

Opens a card. The behavior depends on where the embed is running:

Inside a board (the page URL is a board): the card opens in that board’s side panel.
Anywhere else (for example the dashboard): the card opens in a fullscreen modal, the same as open-card-view.

await aptly.openCardPane({ cardId: "abc123" });

Field	Type	Required	Description
`cardId`	string	Yes	The `_id` of the card to open. Not validated by Aptly.

`open-card-view`

Opens a card in a fullscreen detail view (a floating modal, 90% wide by 95% tall), whether or not the embed is inside a board.

await aptly.openCardView({ cardId: "abc123" });

Field	Type	Required	Description
`cardId`	string	Yes	The `_id` of the card to open. Not validated by Aptly.

`start-dialer`

Opens the Aptly phone dialer with a number pre-filled.

await aptly.startDialer({ number: "+15551234567", name: "Jane Smith" });

Field	Type	Required	Description
`number`	string	Yes	Phone number to call. E.164 (`+15551234567`) is recommended; Aptly does not validate it.
`name`	string	No	Contact name to display in the dialer.

Provider behavior: if the user has no phone channel, Aptly falls back to a tel: link. If the user has both a Twilio and a RingCentral channel, they are asked to pick one.

`open-email-composer`

Opens a new email compose window, optionally pre-filled.

await aptly.openEmailComposer({
  to: [{ value: "[email protected]", label: "Jane Smith" }],
  subject: "Follow-up on your application",
  content: "<p>Hi there,</p><p>Just following up...</p>"
});

Field	Type	Required	Description
`to`	string \| string[] \| `{ value, label }[]`	No	Pre-filled recipients. A single string is one recipient. In an array, each entry is either a string (used as both value and label) or a ready-made `{ value, label }` object. An empty array pre-fills nothing.
`subject`	string	No	Pre-filled subject line. Also used as the composer window title (default `New Message`).
`content`	string	No	Pre-filled body. HTML in email mode.
`composeMode`	`'email'` \| `'sms'`	No	Defaults to `'email'`. If you pass `'sms'`, the SMS composer opens instead and `to` should be phone numbers.
`aptletInstanceId`	string	No	Card `_id` to link the message to.
`applicationId`	string	No	Application `_id` to associate the message with. Passed through to the composer unchanged.

The composer opens as a new outbound message; Aptly creates a discussion thread for it automatically.

`open-sms-composer`

Opens a new SMS compose window, optionally pre-filled. It takes the same fields as open-email-composer; only the defaults and the meaning of to and content differ.

await aptly.openSMSComposer({
  to: "+15551234567",
  content: "Hi Jane, just following up on your tour request."
});

Field	Type	Required	Description
`to`	string \| string[] \| `{ value, label }[]`	No	Pre-filled recipients, as phone numbers. Same shapes as `open-email-composer`.
`content`	string	No	Pre-filled message text. Plain text, not HTML. The composer refuses to send more than 1,600 characters.
`subject`	string	No	Used as the composer window title only.
`composeMode`	`'email'` \| `'sms'`	No	Defaults to `'sms'`. If you pass `'email'`, the email composer opens instead.
`aptletInstanceId`	string	No	Card `_id` to link the message to.
`applicationId`	string	No	Application `_id` to associate the message with. Passed through to the composer unchanged.

`create-event`

Opens the calendar event editor.

await aptly.createEvent({
  recipients: [{ value: "[email protected]", label: "Alex Tenant" }]
});

Field	Type	Required	Description
`recipients`	`{ value, label }[]`	No	Pre-filled attendees. `value` is the email address and `label` is the display name. Objects shaped `{ email, name }` are not recognized by the editor.
`date`	ISO 8601 string	No	Parsed to a date and handed to the editor, but the current editor does not read it, so it has no visible effect today. The event starts at the next quarter hour. Invalid dates are dropped.
`comments`	string	No	Handed to the editor, but the current editor does not read it (it reads a different prop for the description), so it has no visible effect today.

Only recipients is applied today. Do not rely on date or comments until this page says otherwise.

`create-card`

Opens the new-card form. What you get depends on where the embed is running:

Inside a board (the page URL is a board): the create-card dialog opens for the board named by boardId (it does not have to be the board you are on), pre-filled from fields. If boardId is missing, the dialog opens on a “Choose a Board” step.
On the dashboard: the dashboard’s create-card dialog opens. The board picker starts on the user’s remembered dashboard board if they have one, otherwise on boardId. fields is ignored in this case.
On any other page (inbox, contacts, and so on): nothing visible happens, although the call still reports success: true.

await aptly.createCard({
  boardId: "board-uuid-here",
  fields: {
    name: "New Applicant",
    "field-uuid-for-email": "[email protected]"
  }
});

Field	Type	Required	Description
`boardId`	string	Yes	UUID of the board to create the card on.
`fields`	object	No	Values to pre-fill, in a board (not dashboard) context only. Keys are field UUIDs from the board’s schema, plus `name` for the card name. There are no other well-known keys (for example, `email` is not recognized), and values use each field type’s stored format.

`create-task`

Opens the task creation form, optionally pre-filled. Common use case: a “remind me later” button that pre-fills a future due date.

await aptly.createTask({
  title: "Follow up with tenant",
  dueAt: "2026-06-15T09:00:00.000Z",
  priority: "high",
  note: "Check in about lease renewal"
});

Field	Type	Required	Description
`title`	string	No	Pre-filled task title. The form requires a title before it can be created.
`dueAt`	ISO 8601 string	No	Pre-filled due date. Aptly converts it with `new Date(dueAt)`. If omitted, the Due At field starts empty and the user must pick a date. The picker is date-only, so re-picking a date sets 9:00 AM.
`activityLogType`	`'todo'` \| `'email'` \| `'sms'` \| `'voice'`	No	Task type. Defaults to `'todo'`. Not shown in the form; it is saved as given.
`priority`	`'asap'` \| `'high'` \| `'medium'` \| `'low'`	No	Pre-filled priority. Defaults to `'low'`.
`note`	string	No	Saved as the task’s description. Not shown in the form, so the user cannot see or edit it before creating.
`assigneeId`	string	No	User `_id` to pre-assign the task to. Defaults to the current user.
`aptletInstanceId`	string	No	Card `_id` to link the task to.
`aptletUuid`	string	No	Board UUID for context.

The form itself shows Title, Assignee, Priority and Due At. The other fields are carried through and saved when the user clicks Create.

`create-contact`

Opens the contact creation modal, optionally pre-filled.

await aptly.createContact({
  firstname: "Jane",
  lastname: "Smith",
  phone: "+14155551234",
  email: "[email protected]"
});

Field	Type	Required	Description
`firstname`	string	No	Pre-filled first name.
`lastname`	string	No	Pre-filled last name.
`phone`	string \| `{ type, number }[]`	No	Pre-filled phone. A string is saved as a `mobile` number. An array is used as given.
`email`	string	No	Pre-filled email address. A single string (arrays are not supported).
`company`	string	No	Pre-filled company name.
`title`	string	No	Pre-filled job title.

Any other key is ignored.

`navigate-to-contact`

Opens a contact’s record in a floating panel titled “Contact”.

await aptly.navigateToContact({ contactId: "person123" });

Field	Type	Required	Description
`contactId`	string	Yes	The `_id` of the person record to open. Not validated by Aptly.

`open-conversation`

Opens an email or SMS conversation thread in a floating panel, given its stream (discussion) _id.

await aptly.openConversation({ streamId: "stream123", title: "Jane Smith" });

Field	Type	Required	Description
`streamId`	string	Yes	The `_id` of the conversation (stream) to open. Must be a non-empty string, otherwise the call resolves `success: false`.
`title`	string	No	Title shown on the panel’s tab.

Troubleshooting

Action fires but nothing happens. Check that the action is listed under Allowed Actions for the specific embed where your app is running. Permission is configured per embed, not globally. Also check the per-action notes above: create-card does nothing outside a board or the dashboard, and success: true only means the action was dispatched. Response says success: false, error: 'Not permitted'. The action is not in the embed’s allowed list. An admin needs to enable it in the app or board settings. No response message at all. Ensure your app is loaded inside an Aptly embed (not a standalone tab) and that the message is sent via window.parent. The SDK wrappers handle this correctly and resolve { success: false, error: 'timeout' } after 3 seconds if nothing comes back. open-conversation returns success: false with no error. streamId was missing or not a string. create-event ignores my date or description. The event editor currently applies only recipients; date and comments are accepted but not used. create-event attendees show up blank or wrong. Pass recipients as { value: email, label: name }, not { email, name }. create-card opens without my values. Pre-fill works only inside a board, and keys must be field UUIDs (or name). On the dashboard, fields is ignored. open-email-composer or open-sms-composer opens but the To field is empty. Pass to as a string, an array of strings, or an array of { value, label } objects. An empty array or a missing to leaves the field empty for the user to fill in.

Getting Started

Guides

Reference

Using the Aptly SDK (recommended)

Action reference at a glance

Raw postMessage

What `success` means

Enabling actions for your app

Available actions

`open-card-pane`

`open-card-view`

`start-dialer`

`open-email-composer`

`open-sms-composer`

`create-event`

`create-card`

`create-task`

`create-contact`

`navigate-to-contact`

`open-conversation`

Troubleshooting

​Using the Aptly SDK (recommended)

​Action reference at a glance

​Raw postMessage

​What success means

​Enabling actions for your app

​Available actions

​open-card-pane

​open-card-view

​start-dialer

​open-email-composer

​open-sms-composer

​create-event

​create-card

​create-task

​create-contact

​navigate-to-contact

​open-conversation

​Troubleshooting

Using the Aptly SDK (recommended)

Action reference at a glance

Raw postMessage

What `success` means

Enabling actions for your app

Available actions

`open-card-pane`

`open-card-view`

`start-dialer`

`open-email-composer`

`open-sms-composer`

`create-event`

`create-card`

`create-task`

`create-contact`

`navigate-to-contact`

`open-conversation`

Troubleshooting