시작하기 (튜토리얼)

{
	"method": "function name", // 실행하려는 동작의 명칭
	"params": {
		"chat": {
			"type": "group | directChat | userChat",
			"id": "groupId | directChatId | userChatId"
		},
		"trigger": {
			"type": "string",
			"attributes": {}
		},
		"inputs": {} // inputs는 배열 혹은 object일 수 있습니다.
	},
	"context": {
		"channel": {
			"id": "number" // 이 요청이 트리거 된 Channel Id
		},
		"caller": {
			"type": "user | manager | app" ,// 요청을 트리거 한 주체
			"id": "number" // caller의 id
		}
}

{
	"type": "wam",
	"attributes": {
		"appId": "app id", // 앱 등록 시 생성 됨
		"name": "name of the wam",
		"wamArgs": {} // 다른 function 호출 시 이용되어야 할 값의 모음
	}
}

{
	"result": {
		"type": "string",
		"attributes": {} // function 처리 결과 혹은 이 function 실행 후 WAM의 연결 동작에 필요한 값의 모음
	},
	"error": {
		"type": "error type",
		"message": "error message"
	}
}

{
	"method": "tutorial",
	"params": null, // wam을 호출하기 위해 아무런 query를 필요로 하지 않습니다.
	"context": {
		"caller": {
			"type": "manager", // 앱은 WAM에서 '매니저로 그룹에 메시지 전송' 권한만 사용하도록 설정하였기 때문에 caller type(wam을 요청한 주체)이 매니저인지 검증해야 합니다.
			"id": "managerId"
		}
	}
}

{
	"type": "wam",
	"attributes": {
		"appId": "app id", // app-tutorial의 app id
		"name": "tutorial",
		"wamArgs": {
			"message": "This is a test message sent by a manager.", // 매니저는 여기서 제공하는 문장을 wam 인터페이스를 통해 그룹 메시지로 전송합니다.
			"managerId": "caller.id" // wam에서는 이 값을 통해 어떤 매니저가 wam을 트리거 해 그룹 메시지를 전송하려고 시도하는지 알 수 있습니다.
		}
}

{
	"method": "sendAsBot",
	"params": {
		"groupId": "group id", // 어떤 그룹에 메시지를 작성할까요?
		"rootMessageId": "root message id", // 메시지를 가장 상위 그룹 채팅창에 작성하지 않고 스레드에 작성하고자 할 경우 이 값(스레드의 첫 번째 메시지의 id)이 같이 주어져야 합니다.
		"broadcast": true // 이 그룹 메시지를 스레드에 작성할 때, 스레드 바깥의 상위 그룹 채팅창에 내용을 함께 전파합니다.
	},
	"context": {
		"channel": {
			"id": "channel id" // 이 채널에 그룹 메시지를 전송합니다.
		},
		"caller": null // 봇 메시지 전송 동작이므로 function 트리거 주체는 고려하지 않습니다. 즉, 검증하지 않습니다.
}

{
	"result": {
		"type": "string",
		"attributes": {} // 봇 메시지 전송 성공 여부와 관계 없이 빈 값을 반환합니다. (이후로 아무 동작도 실행하지 않고 wam을 종료합니다.)
	}
}

// Token은 무조건 Unique Key와 Duration을 가지고 있습니다.
type Token interface {
	Key() string
	Duration() time.Duration
}

type AccessToken struct {
	ChannelID string // 채널 토큰이므로 ChannelID 마다 토큰을 발급 받아야 합니다.
	Token     string
}

func (t AccessToken) Key() string {
	return fmt.Sprintf("app-%s-access-token-%s", config.Get().AppID, t.ChannelID)
}

// real duration is 30 minutes
func (AccessToken) Duration() time.Duration {
	return time.Minute*30 - time.Minute*1
}

type RefreshToken struct {
	ChannelID string // 채널 토큰이므로 ChannelID 마다 토큰을 발급 받아야 합니다.
	Token     string
}

func (t RefreshToken) Key() string {
	return fmt.Sprintf("app-%s-refresh-token-%s", config.Get().AppID, t.ChannelID)
}

// real duration is 7 days
func (RefreshToken) Duration() time.Duration {
	return time.Hour*24*7 - time.Minute*1
}

type NativeFunctionRequest = {
	method: string // issueToken | refreshToken
	params: any // IssueTokenParams | RefreshTokenParams
};

type NativeFunctionResponse = {
	error:  NativeError     
	result: any // TokenResponse
};

type NativeError = {
	type:    string
	message: string
};

type NativeFunctionRequest[REQ any] struct {
	Method string // issueToken | refreshToken
	Params REQ // IssueTokenParams | RefreshTokenParams
}

type NativeFunctionResponse struct {
	Error  NativeError     `json:"error,omitempty"`
	Result json.RawMessage `json:"result,omitempty"` // TokenResponse
}

type NativeError struct {
	Type    string `json:"type"`
	Message string `json:"message"`
}

// NativeFunctionRequest.Params
type IssueTokenParams = {
	secret:    string
	channelID: string 
}

// NativeFunctionRequest.Params
type RefreshTokenParams = {
	refreshToken: string 
}

// NativeFunctionResponse.Result
type TokenResponse = {
	accessToken:  string 
	refreshToken: string 
}

// NativeFunctionRequest.Params
type IssueTokenParams struct {
	Secret    string `json:"secret"`
	ChannelID string `json:"channelId"`
}

// NativeFunctionRequest.Params
type RefreshTokenParams struct {
	RefreshToken string `json:"refreshToken"`
}

// NativeFunctionResponse.Result
type TokenResponse struct {
	AccessToken  string `json:"accessToken"`
	RefreshToken string `json:"refreshToken"`
}

async function requestIssueToken(channelId?: string) : Promise<[string, string, number]> {
    let body = {
        method: 'issueToken',
        params: {
            secret: appConfig.appSecret,
            channelId: channelId
        }
    };

    const headers = {
        'Content-Type': 'application/json'
    };
    
    const response = await axios.put(appConfig.appstoreURL, body, { headers });

    const accessToken = response.data.result.accessToken;
    const refreshToken = response.data.result.refreshToken;    
    const expiresAt = new Date().getTime() / 1000 + response.data.result.expiresIn - 5;    

    return [accessToken, refreshToken, expiresAt];
}

const [accessToken, refreshToken, expiresAt]: [string, string, number] | undefined = await requestIssueToken(channelId);

func (c *authClient) IssueToken(ctx context.Context, channelID string) (*dto.TokenResponse, error) {
	body := native.NativeFunctionRequest[dto.IssueTokenParams]{
		Method: "issueToken",
		Params: dto.IssueTokenParams{
			Secret:    config.Get().AppSecret,
			ChannelID: channelID,
		},
	}

	res, err := c.R().
		SetHeader("Content-Type", "application/json").
		SetBody(body).
		Put("/general/v1/native/functions")
	if err != nil || res.IsError() {
		return nil, errors.Wrapf(err, "failed to request issueToken")
	}

	var nres native.NativeFunctionResponse
	if err := json.Unmarshal(res.Body(), &nres); err != nil {
		return nil, errors.Wrapf(err, "failed to request issueToken")
	}

	var tres dto.TokenResponse
	if err := json.Unmarshal(nres.Result, &tres); err != nil {
		return nil, errors.Wrapf(err, "failed to request issueToken")
	}
	return &tres, nil
}

app.use(express.json());
app.use(`/resource/wam/${WAM_NAME}`, express.static(path.join(__dirname, '../client/dist')));
app.listen(port, () => {
    console.log(`Server is running at http://localhost:${port}`);
});

// handler와 wam 파일의 상대적인 위치 
//
// wam/
// 	resources/wam/tutorial/
// 		#index.html -> 빌드된 WAM 페이지
// 		...
//	#handler.go

//go:embed resources/*
var resources embed.FS

type Handler struct {
}

func NewHandler() *Handler {
	return &Handler{}
}
 
func (h *Handler) Path() string {
	// <샘플 앱의 루트 엔드포인트>/resource/wam/tutorial로 WAM에 접근할 수 있도록 열어줍니다.
	return "/resource/wam/tutorial"
}

func (h *Handler) Register(router libhttp.Router) { // libhhttp.Router는 gin.IRouter의 구현체입니다.
	static, err := fs.Sub(resources, "resources/wam/tutorial")
	if err != nil {
		panic(err)
	}
	// 이 엔드포인트에 접근하면 wam의 정적 페이지를 얻을 수 있습니다.
	router.StaticFS("", http.FS(static))
}

<서버 설정에 등록한 WAM Endpoint>/<해당 Command의 Action Function Name>

const [accessToken, refreshToken, expiresAt]: [string, string, number] | undefined = await requestIssueToken();
//await requestIssueToken(channelId)의 경우 해당 channelId를 갖는 채널에 대한 토큰이 발급됩니다.

func (c *authClient) IssueAppToken(ctx context.Context) (*dto.TokenResponse, error) {
	body := native.NativeFunctionRequest[dto.IssueTokenParams]{
		Method: "issueToken",
		Params: dto.IssueTokenParams{
			Secret:    config.Get().AppSecret,
			// 요청에 ChannelID가 없으면 채널 토큰이 아닌 앱 토큰을 발급합니다.
			// ChannelID: channelID,
		},
	}

	...
}

type Command = {
	name:               string
	scope:              string
	description:        string 
	actionFunctionName: string
	alfMode:            string
	enabledByDefault:   bool 
}

type RegisterCommandsParam = {
	appId:           string
	commands:        Command[]
}

type Command struct {
	Name               string `json:"name"`
	Scope              string `json:"scope"`
	Description        string `json:"description"`
	ActionFunctionName string `json:"actionFunctionName"`
	ALFMode            string `json:"alfMode"`
	EnabledByDefault   bool   `json:"enabledByDefault"`
}

type RegisterCommandsParam struct {
	AppID           string    `json:"appId"`
	Commands        []Command `json:"commands"`
}

async function functionHandler(body: any) {
    const method = body.method;
    const callerId = body.context.caller.id;
    const channelId = body.context.channel.id;

    switch (method) {
        case 'openWam':
            return openWam(WAM_NAME, callerId);
        case 'writeGroupMessageAsBot':
            return await writeGroupMessageAsBot(
                channelId,
                body.params.chatId,
                body.params.text,
                body.params.rootMessageId
            );
    }
}


app.use(express.json());

app.put('/function', (req: Request, res: Response) => {
  if (typeof req.headers['x-signature'] !== 'string' || verification(req.headers['x-signature'], JSON.stringify(req.body)) === false) {
    res.status(401).send('Unauthorized');
  }
  functionHandler(req.body).then(result => {
    res.send(result);
  });
});

app.listen(appConfig.port, () => {
  console.log(`Server is running at http://localhost:${appConfig.port}`);
});

// ...

func (h *Handler) Path() string {
	// /functions endpoint로 요청을 받습니다.
	return "/functions"
}

func (h *Handler) Register(router libhttp.Router) {
	// PUT /functions로 요청이 들어오면 Handler.Function 메서드로 요청을 처리합니다.
	router.PUT("", h.Function)
}

func (h *Handler) Function(ctx *gin.Context) {
	var req dto.JsonFunctionRequest
	if err := ctx.ShouldBindBodyWith(&req, binding.JSON); err != nil {
		ctx.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}

	var res *dto.JsonFunctionResponse
	
	switch req.Method {
	case tutorialMethod:
		res = h.tutorial(ctx, req.Params.Input, req.Context)
	case sendAsBotMethod:
		res = h.sendAsBot(ctx, req.Params.Input, req.Context)
	default:
		ctx.JSON(
			http.StatusOK,
			dto.JsonFunctionResponse{
				Error: &dto.Error{
					Message: "invalid method, " + req.Method,
				},
			},
		)
		return
	}

	ctx.JSON(http.StatusOK, res)
}

{
	"type": "wam",
	"attributes": {
		"appId": "...", // app-tutorial의 app id
		"name": "tutorial",
		"wamArgs": {
			"message": "This is a test message sent by a manager.", // 매니저는 여기서 제공하는 문장을 wam 인터페이스를 통해 그룹 메시지로 전송합니다.
			"managerId": "caller.id" // wam에서는 이 값을 통해 어떤 매니저가 wam을 트리거 해 그룹 메시지를 전송하려고 시도하는지 알 수 있습니다.
		}
}

async function writeGroupMessageAsBot(channelId: string, chatId: string, text: string, rootMessageId?: string) {
    const body = {
        method: "writeGroupMessage",
        params: {
            channelId: channelId,
            groupId: chatId,
            rootMessageId: rootMessageId,
            broadcast: false,
            dto: { 
                plainText: text,
                botName: "Bot"
            }
        }
    }

    const channelToken = await getChannelToken(channelId);

    const headers = {
        'x-access-token': channelToken[0],
        'Content-Type': 'application/json'
    };

    const response = await axios.put(appConfig.appstoreURL, body, { headers });

    if (response.data.error !== undefined) {
        throw new Error();
    }
    
    return ({'result': {}});
}

func (h *Handler) sendAsBot(
	ctx context.Context,
	params json.RawMessage,
	fnCtx dto.Context,
) *dto.JsonFunctionResponse {
	// ...
	// parsing 로직 생략

  _, err := h.client.WritePlainTextToGroup(
		ctx,
		appstoredto.PlainTextGroupMessage{
			ChannelID:     fnCtx.Channel.ID,
			GroupID:       param.GroupID,
			Broadcast:     param.Broadcast,
			RootMessageID: param.RootMessageID,
			Message:       sendAsBotMsg,
		},
	)
	if err != nil {
		return &dto.JsonFunctionResponse{
			Error: &dto.Error{
				Message: "failed to send message as a bot",
			},
		}
	}

	// response parsing 로직 생략
}

$ git clone https://github.com/channel-io/app-tutorial

stage: development

appId: # app id registered in app-store
appSecret: # app secret issued by a manager

api:
  public:
    http:
      port: 3022

appStore:
  baseUrl: https://app-store-api.channel.io

bot:
  name: AppTutorialBot

$ make dev

$ ngrok http http://localhost:3022 --subdomain app-tutorial --region ap

ngrok                                                                                          (Ctrl+C to quit)
                                                                                                               
Full request capture now available in your browser: https://ngrok.com/r/ti                                     
                                                                                                               
Session Status                online                                                                           
Account                       <Your Account> (Plan: ...)                                                  
Version                       3.9.0                                                                            
Region                        Asia Pacific (ap)                                                                
Latency                       83ms                                                                             
Web Interface                 http://127.0.0.1:4040                                                            
Forwarding                    https://app-tutorial.ap.ngrok.io -> http://localhost:3022                        
                                                                                                               
Connections                   ttl     opn     rt1     rt5     p50     p90                                      
                              0       0       0.00    0.00    0.00    0.00