Skip to content
Instant

Developers

Unfurls and App Home

Make links to your service look like your service, and give everyone a page of their own in your bot’s DM.

Link Unfurls

On the bot’s page, list up to 5 Unfurl Domains (example.com covers its subdomains), turn on the links:read and links:write scopes, and tick the link_shared event.

When someone shares a link to those domains in a channel or DM the bot is in, it gets Slack’s link_shared with channel, user, message_ts, unfurl_id and the links (domain and url). Answer with chat.unfurl and a Slack attachment for each URL:

app.event('link_shared', async ({ event, client }) => {
  const unfurls = {};
  for (const { url } of event.links) {
    const t = await tickets.byUrl(url);
    unfurls[url] = {
      color: t.open ? '#2f9e44' : '#868e96',
      title: `${t.key} · ${t.title}`,
      title_link: url,
      text: t.summary,
      fields: [
        { title: 'Status', value: t.status, short: true },
        { title: 'Owner', value: t.owner, short: true },
      ],
      thumb_url: t.ownerAvatar,
      footer: 'Tickets',
    };
  }
  await client.chat.unfurl({ channel: event.channel, ts: event.message_ts, unfurls });
});
  • An attachment can have title, title_link, author_name, pretext, text (or blocks, read as text), color (hex, or good, warning, danger), fields, image_url, thumb_url and footer.
  • The card replaces that link’s usual preview, for everyone at once, under the bot’s name with its color down the edge. Unfurling the same link again replaces it.
  • Only links in that message, on the bot’s own domains (else cannot_unfurl_url). Images are copied to Instant, so readers never load anything from your server.

App Home

Every bot has a Home tab, first in each person’s DM with it. What it shows is up to the bot, and can differ for every person: their tickets, their settings, today’s on-call.

Tick the app_home_opened event. When someone opens the tab, the bot hears it (with user, channel, tab: "home" and the current view, if any) and publishes their Home with views.publish:

app.event('app_home_opened', async ({ event, client }) => {
  const mine = await tickets.ownedBy(event.user);
  await client.views.publish({
    user_id: event.user,
    view: {
      type: 'home',
      blocks: [
        { type: 'header', text: { type: 'plain_text', text: 'Your Tickets' } },
        ...mine.map((t) => ({
          type: 'section',
          text: { type: 'mrkdwn', text: `*${t.key}* ${t.title}` },
          accessory: { type: 'button', action_id: 'open_ticket', value: t.key, text: { type: 'plain_text', text: 'Open' } },
        })),
        { type: 'divider' },
        { type: 'actions', elements: [{ type: 'button', action_id: 'new_ticket', style: 'primary', text: { type: 'plain_text', text: 'New Ticket' } }] },
      ],
    },
  });
});
  • A Home can hold header, section (with fields, and a button or menu as its accessory), context, divider and actions with buttons and menus. Inputs belong in forms and are left out.
  • It updates at once on every device the person has open. Pass the hash from the last view to refuse a stale write (hash_conflict).
  • A click sends block_actions with container: { type: "view" }, the view and a trigger_id, so app.action('new_ticket', …) can open a form or publish the Home again.

Build Your First Bot

Make a bot in Settings › Bots & Apps and post your first message in a minute.

Join NowSee Pricing