create_direct_message

Send direct messages to users or groups with text-to-speech audio generation and link attachments in Carbon Voice.

Instructions

Send a Direct Message (DM) to a User or a Group of Users. In order to create a Direct Message, you must provide transcript or link attachments.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`to`	Yes
`workspace_id`	No	The workspace ID to send the message to	personal
`transcript`	No	The Message transcript will be used to generate audio using text-to-speech
`links`	No	Array of links to be attached to the message
`from_message_type`	No	From Message type	NewMessage
`from_message_id`	No	Message ID to be used as a base for the new message. (Optional only when from_message_type is NewMessage)

Implementation Reference

src/server.ts:228-240 (handler)

Inline asynchronous handler function that executes the core logic of the 'create_direct_message' tool: calls simplifiedApi.sendDirectMessage with args and auth token, formats the response, and handles errors.

async (args: SendDirectMessage, { authInfo }): Promise<McpToolResponse> => {
  try {
    return formatToMCPToolResponse(
      await simplifiedApi.sendDirectMessage(
        args,
        setCarbonVoiceAuthHeader(authInfo?.token),
      ),
    );
  } catch (error) {
    logger.error('Error creating direct message:', { args, error });
    return formatToMCPToolResponse(error);
  }
},

src/server.ts:216-241 (registration)

Registration of the 'create_direct_message' MCP tool, specifying description, input schema (sendDirectMessageBody.shape), annotations, and inline handler.

server.registerTool(
  'create_direct_message',
  {
    description:
      'Send a Direct Message (DM) to a User or a Group of Users. ' +
      'In order to create a Direct Message, you must provide transcript or link attachments.',
    inputSchema: sendDirectMessageBody.shape,
    annotations: {
      readOnlyHint: false,
      destructiveHint: false,
    },
  },
  async (args: SendDirectMessage, { authInfo }): Promise<McpToolResponse> => {
    try {
      return formatToMCPToolResponse(
        await simplifiedApi.sendDirectMessage(
          args,
          setCarbonVoiceAuthHeader(authInfo?.token),
        ),
      );
    } catch (error) {
      logger.error('Error creating direct message:', { args, error });
      return formatToMCPToolResponse(error);
    }
  },
);

src/generated/carbon-voice-api/CarbonVoiceSimplifiedAPI.zod.ts:776-786 (schema)

Zod input schema definition (sendDirectMessageBody) for validating tool arguments, including 'to' recipients, workspace_id, transcript, links, etc. Referenced as inputSchema.shape in registration.

export const sendDirectMessageBody = zod.object({
  "to": zod.object({
  "user_ids": zod.array(zod.string()).optional().describe('Array of user IDs to send the message to'),
  "emails": zod.array(zod.string()).optional().describe('Array of email addresses to send the message to')
}),
  "workspace_id": zod.string().default(sendDirectMessageBodyWorkspaceIdDefault).describe('The workspace ID to send the message to'),
  "transcript": zod.string().optional().describe('The Message transcript will be used to generate audio using text-to-speech'),
  "links": zod.array(zod.string()).optional().describe('Array of links to be attached to the message'),
  "from_message_type": zod.enum(['PreRecorded', 'NewMessage', 'Forward']).default(sendDirectMessageBodyFromMessageTypeDefault).describe('From Message type'),
  "from_message_id": zod.string().optional().describe('Message ID to be used as a base for the new message. (Optional only when from_message_type is NewMessage)')
})

src/generated/carbon-voice-api.ts:363-376 (helper)

API helper function simplifiedApi.sendDirectMessage: performs POST request to /simplified/messages/direct with SendDirectMessage payload, called by the tool handler.

const sendDirectMessage = (
  sendDirectMessage: SendDirectMessage,
  options?: SecondParameter<typeof mutator>,
) => {
  return mutator<GetMessageResponse>(
    {
      url: `/simplified/messages/direct`,
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      data: sendDirectMessage,
    },
    options,
  );
};

src/generated/models/SendDirectMessage.ts:82-94 (schema)

TypeScript interface SendDirectMessage defining the shape of arguments for the tool and API call.

export interface SendDirectMessage {
  to: ToRecipient;
  /** The workspace ID to send the message to */
  workspace_id?: string;
  /** The Message transcript will be used to generate audio using text-to-speech */
  transcript?: string;
  /** Array of links to be attached to the message */
  links?: string[];
  /** From Message type */
  from_message_type?: SendDirectMessageFromMessageType;
  /** Message ID to be used as a base for the new message. (Optional only when from_message_type is NewMessage) */
  from_message_id?: string;
}

Carbon Voice