run_ai_action_for_shared_link
Execute AI prompts on shared Carbon Voice links to analyze conversations or voice memos and generate responses in specified languages.
Instructions
Run an AI Action (Prompt) for a shared link. You can run an AI Action for a shared link by its ID or a list of shared link IDs. You can also provide the language of the response.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prompt_id | Yes | ||
| share_link_ids | Yes | ||
| language | No |
Implementation Reference
- src/server.ts:899-914 (handler)The handler function for the 'run_ai_action_for_shared_link' MCP tool. It calls the simplified API to create an AI response for shared links, handles authentication, formats the MCP tool response, and logs errors.async ( args: CreateShareLinkAIResponse, { authInfo }, ): Promise<McpToolResponse> => { try { return formatToMCPToolResponse( await simplifiedApi.createShareLinkAIResponse( args, setCarbonVoiceAuthHeader(authInfo?.token), ), ); } catch (error) { logger.error('Error running ai action for shared link:', { error }); return formatToMCPToolResponse(error); } },
- src/server.ts:887-915 (registration)Registration of the 'run_ai_action_for_shared_link' tool using server.registerTool, including description, input schema, annotations, and inline handler.server.registerTool( 'run_ai_action_for_shared_link', { description: 'Run an AI Action (Prompt) for a shared link. You can run an AI Action for a shared link by its ID or a list of shared link IDs. ' + 'You can also provide the language of the response.', inputSchema: createShareLinkAIResponseBody.shape, annotations: { readOnlyHint: false, destructiveHint: false, }, }, async ( args: CreateShareLinkAIResponse, { authInfo }, ): Promise<McpToolResponse> => { try { return formatToMCPToolResponse( await simplifiedApi.createShareLinkAIResponse( args, setCarbonVoiceAuthHeader(authInfo?.token), ), ); } catch (error) { logger.error('Error running ai action for shared link:', { error }); return formatToMCPToolResponse(error); } }, );
- Zod schema definition for the input to the tool: createShareLinkAIResponseBody, used as inputSchema in registration. Defines prompt_id, share_link_ids array, and optional language.export const createShareLinkAIResponseBody = zod.object({ "prompt_id": zod.string(), "share_link_ids": zod.array(zod.string()), "language": zod.string().optional() })
- TypeScript interface for CreateShareLinkAIResponse, used as type for args in the handler./** * Generated by orval v7.9.0 🍺 * Do not edit manually. * Carbon Voice Simplified API * # Introduction The simplified version of the Carbon Voice API is designed to enhance usability for third-party clients looking to seamlessly integrate with our application. By streamlining authentication methods, providing clear error handling guidelines, and implementing straightforward rate limiting policies, we ensure that developers can quickly and efficiently connect to our services. This user-friendly approach minimizes complexity, making it easier for external applications to leverage the powerful communication features of Carbon Voice without extensive technical overhead. This API is designed for people who feel comfortable integrating with RESTful APIs. ## Full API Version We also have a full version of the API. You can find it [here](/docs). ## Terminology * **Workspace**: An area that groups together people and Conversations. * **Conversation**: A channel of communication. A grouping of people and messages related to a given topic. * **Collaborators**: A group of people who are part of a Conversation. * **Discussion**: Any post into a conversation * **CarbonLink**: A link (on a website, QR code, or phone call) to start a conversation. ## BaseURL This API is served over HTTPS. All URLs referenced in the documentation have the following base: https://api.carbonvoice.app/api/simplified. ## Authentication There are three ways to authenticate with this API: * with an OAuth2 Access Token in the Authorization request header field (which uses the Bearer authentication scheme to transmit the Access Token) * with your Client ID and Client Secret credentials * with a PXToken Each endpoint supports only one option. <SecurityDefinitions /> ## Errors When an error occurs, you will receive an error object. Most of these error objects contain an error code and an error description so that your applications can more efficiently identify the problem. If you get an 4xx HTTP response code, then you can assume that there is a bad request from your end. In this case, check the [Error Responses section](#section/Introduction/Error-Responses) for more context. 5xx errors suggest a problem on our end, so in this case, check [Carbon Voice's Status](https://status.carbonvoice.app) to see how our systems are doing. In any other case you can use our support options. ## Error Responses `{ "success": false, requestId: "uuid", errmsg: "error message"` ## Rate-Limiting This API is subject to rate limiting. The limits differ per endpoint. If you exceed the provided rate limit for a given endpoint, you will receive the 429 Too Many Requests response with the following message: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. For details on rate limiting, refer to Rate Limit Policy. ## Support If you have problems or need help with your case, you can always reach out to our Support. * OpenAPI spec version: 1.0.0 */ export interface CreateShareLinkAIResponse {
- Utility function to format API responses or errors into MCP ToolResponse format, used in the handler.import { McpToolResponse } from '../interfaces'; import { getTraceId } from '../transports/http/utils/request-context'; const isErrorWithDetails = ( error: unknown, ): error is { code?: string; message?: string; details?: unknown } => { return typeof error === 'object' && error !== null; }; export const formatToMCPToolResponse = (data: unknown): McpToolResponse => { try { return { content: [{ type: 'text', text: JSON.stringify(data) }], }; } catch (error: unknown) { logger.error('Error formatting response:', { data, error }); let code = 'UNKNOWN_ERROR'; let message = 'Error formatting response'; let details; if (isErrorWithDetails(error)) { code = error?.code || code;