App Development

Typescript Interface

Learn about the typescript interface your app must implement for proper integration with the platform.

To integrate your app with the platform, your app’s src/index.ts file must export a default object implementing specific functions. These functions handle different stages of the app’s lifecycle, such as requests, installations, and actions.

The preInstall and postInstall functions are highly recommended for all apps - even those not taking advantage of the rest of the serverless platform. All other functions are optional.

Example Export

Here is an example of how to structure your src/index.ts file:

1export default {
2 async handleRequest({request, getSettings, ...rest}) {
3 // Your url request handling logic here
4 },
5
6 async preInstall({organizationId, agentId, settings, ...rest}) {
7 // Logic to execute before the app is installed
8 },
9
10 async postInstall({organizationId, agentId, settings, ...rest}) {
11 // Logic to execute after the app is installed
12 },
13
14 async executeAction({actionId, parameters, user, ...rest}) {
15 // Logic to execute specific actions
16 },
17}

Interfaces

AppInterface

Interface implemented by the app entrypoint.

Properties

executeAction()?
1optional executeAction: (payload: {
2 actionId: string;
3 agentId: string;
4 organizationId: string;
5 parameters: Record<string, any>;
6 user: any;
7}) => string | Promise<string>;
Parameters
ParameterTypeDescription
payloadobjectThe action execution payload.
payload.actionIdstringThe ID of the action to be executed.
payload.agentIdstringThe ID of the agent.
payload.organizationIdstringThe ID of the organization.
payload.parametersRecord<string, any>The parameters for the action.
payload.useranyThe user initiating the action.
Returns

string | Promise<string>

string.

feedbackCreated()?
1optional feedbackCreated: (payload: {
2 agentId: string;
3 ctx: Context;
4 feedbacks: Feedback[];
5 organizationId: string;
6 settings: Record<string, any>;
7}) => void | Promise<void>;
Parameters
ParameterTypeDescription
payloadobjectThe feedback created payload.
payload.agentIdstringThe ID of the agent.
payload.ctxContextThe context containing the waitUntil method.
payload.feedbacksFeedback[]The feedbacks submitted by the user.
payload.organizationIdstringThe ID of the organization.
payload.settingsRecord<string, any>The settings for the webhook.
Returns

void | Promise<void>

void.

handleRequest()?
1optional handleRequest: (payload: {
2 ctx: Context;
3 getSettings: (params: {
4 agentId: string;
5 organizationId: string;
6 }) => Promise<any>;
7 request: Request;
8}) => Response | Promise<Response>;
Parameters
ParameterTypeDescription
payloadobjectThe payload containing the request, settings, and context.
payload.ctxContextThe context containing the waitUntil method.
payload.getSettings(params: { agentId: string; organizationId: string; }) => Promise<any>Function to get settings for the given organization and agent.
payload.requestRequestThe incoming HTTP request.
Returns

Response | Promise<Response>

Response.

postInstall()?
1optional postInstall: (payload: {
2 agentId: string;
3 ctx: Context;
4 organizationId: string;
5 settings: Record<string, any>;
6}) => void | Promise<void>;
Parameters
ParameterTypeDescription
payloadobjectThe post-install payload.
payload.agentIdstringThe ID of the agent.
payload.ctxContextThe context containing the waitUntil method.
payload.organizationIdstringThe ID of the organization.
payload.settingsRecord<string, any>The settings for the installation.
Returns

void | Promise<void>

void.

preInstall()?
1optional preInstall: (payload: {
2 agentId: string;
3 ctx: Context;
4 organizationId: string;
5 settings: Record<string, any>;
6}) => void | Promise<void>;
Parameters
ParameterTypeDescription
payloadobjectThe pre-install payload.
payload.agentIdstringThe ID of the agent.
payload.ctxContextThe context containing the waitUntil method.
payload.organizationIdstringThe ID of the organization.
payload.settingsRecord<string, any>The settings for the installation.
Returns

void | Promise<void>

void.


Context

Context type used for providing a waitUntil method.

Methods

waitUntil()
1waitUntil(promise: Promise<any>): void

Allows the function to return without waiting for the promise to finish.

Parameters
ParameterTypeDescription
promisePromise<any>The promise to continue executing even if the function returns.
Returns

void

Example
1ctx.waitUntil(fetchData());

Feedback

Feedback type

Keep consistent with import Feedback from ‘@magi/sdks-developers-typescript/api’

Properties

conversationId
1conversationId: string;

The ID of the conversation the feedback is about

conversationMessageId
1conversationMessageId: string;

The ID of the conversation message the feedback is about

id
1id: string;

The ID of the piece of feedback

text?
1optional text: string;

The feedback text

type
1type: "THUMBS_UP" | "THUMBS_DOWN" | "INSERT" | "HANDOFF";

The type of feedback