Slack: Sends an ephemeral message to a user in a channel

← Chat operations · Get started

Operation slack.chat_postephemeral

Provider route: POST /chat.postEphemeral. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/slack with npm, or alter-sdk-slack with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { SlackIntegration } from "@alter-ai/slack";

async function execute(input: Parameters<SlackIntegration["chat"]["postEphemeral"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new SlackIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.chat.postEphemeral(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_slack import SlackIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = SlackIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.chat.post_ephemeral(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
body	object	Required within parent
body.as_user	boolean	Optional	(Legacy) Pass true to post the message as the authed user. Defaults to true if the chat:write:bot scope is not included. Otherwise, defaults to false.
body.attachments	string	Optional	A JSON-based array of structured attachments, presented as a URL-encoded string.
body.blocks	string	Optional	A JSON-based array of structured blocks, presented as a URL-encoded string.
body.channel	string	Required within parent	Channel, private group, or IM channel to send message to. Can be an encoded ID, or a name.
body.icon_emoji	string	Optional	Emoji to use as the icon for this message. Overrides `icon_url`.
body.icon_url	string	Optional	URL to an image to use as the icon for this message.
body.link_names	boolean	Optional	Find and link channel names and usernames.
body.markdown_text	string	Optional	Accepts message text formatted in markdown. This argument should not be used in conjunction with `blocks` or `text`. Limit this field to 12,000 characters.
body.metadata	string	Optional	JSON object with an `entities` array of work object entity metadata, presented as a URL-encoded string. Only entity metadata is supported: ephemeral messages are not persisted and never dispatch `message_metadata_*` events, so `event_type`/`event_payload` message metadata is ignored here. Each entity requires `entity_type`, `entity_payload`, `external_ref`, and `url`.
body.parse	string	Optional	Change how messages are treated. Defaults to `none`.
body.text	string	Optional	How this field works and whether it is required depends on other fields you use in your API call.
body.thread_ts	string	Optional	Provide another message’s `ts` value to post this message in a thread. Avoid using a reply’s `ts` value; use its parent’s value instead. Ephemeral messages in threads are only shown if there is already an active thread.
body.user	string	Required within parent	`id` of the user who will receive the ephemeral message. The user should be in the channel specified by the `channel` argument.
body.username	string	Optional	Set your bot’s user name.

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	object	Root	Schema for successful response from chat.postEphemeral method
message_ts	string	Optional
ok	boolean	Required within parent	Must equal: true

Policy, approvals and errors

SDK function policy ID: slack.chat_postephemeral. Catalog operation: chat_postEphemeral. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["chat:write"]

Official provider source