Skip to content

Use the Channels CLI

View as Markdown

The socra channels namespace exposes Account-scoped messaging operations. Use it from a terminal or a runtime with terminal access.

Before you start

You need the Socra CLI and an authorized Account session. Install the Channels namespace, then check its commands:

Bash
socra install channels
socra channels --help

If the Account session is missing, run socra account login and select the intended Account. Keep credentials out of messages and shared command output.

Verify the session

Read the current workspace membership:

Bash
socra channels session get

Confirm that the returned membership belongs to the intended Account. An authentication error is not a successful connection.

List channels

Read up to 20 channels:

Bash
socra channels channel list --limit 20

Use the returned IDs when another command requires a channel identifier. An empty authorized result means there are no matching channels available to that request.

Read messages

Replace CHANNEL_ID with the ID of a channel you can access:

Bash
socra channels message list --channel-id CHANNEL_ID --limit 20

The commands above read existing data.

Send a message

Use an existing channel that you have permission to post in. You must be a member of the channel. Sending a message makes its content visible to the conversation's participants and can notify them.

  1. Copy the channel's id from socra channels channel list. A channel ID identifies the conversation; participant user IDs and member record IDs cannot replace it.

  2. Save this JSON as message.json. Replace CHANNEL_ID with the channel ID, replace UNIQUE_MESSAGE_KEY with a new identifier for this message, and enter the text you intend to send. Keep the key between 1 and 128 characters. Use a different key for each new message.

    JSON
    {
  "channel_id": "CHANNEL_ID",
  "client_id": "UNIQUE_MESSAGE_KEY",
  "text": "The report is ready for review."
}

  3. Send the saved request:

    Bash
    socra channels message create --file message.json

  4. Check that the returned message has an id and the intended channel_id and text. To retrieve it again, replace MESSAGE_ID with that returned id:

    Bash
    socra channels message get MESSAGE_ID

Retry after an uncertain response

If the send command times out or loses its connection before returning a result, retry the unchanged message.json with the same Account and sender. Its client_id lets Channels return the existing message when the first send succeeded. Keep the destination and content unchanged for that retry.

If you omit client_id, the CLI generates a new value each time you run the command. Repeating that command can send another message.

If a request reports that the channel is unavailable, check the selected Account, the channel ID, and your channel membership. A channel can be visible in a list without allowing you to post. An archived channel does not accept new messages.

Reply in a thread

To reply to an existing top-level message, add "thread_id": "PARENT_MESSAGE_ID" to the JSON before sending. Replace PARENT_MESSAGE_ID with that message's id. The parent must be a live top-level message in the same channel. Use a new client_id for the reply.

Inspect command options

Use command help for filters and required fields:

Bash
socra channels channel list --help
socra channels message list --help
socra channels message create --help

For the native interface, follow Install Channels.

See also