WhatsApp Template API

개발자 API

승인된 WhatsApp 템플릿을 API 호출 한 번으로 자체 시스템에서 발송하고, 이후 대화는 MonoChat에서 이어 갑니다.

WhatsApp
REST API
API 전용

개요

WhatsApp Template API를 사용하면 CRM, ERP, 이커머스 사이트 또는 모든 백엔드에서 MonoChat을 통해 승인된 WhatsApp 템플릿 메시지를 고객에게 보낼 수 있습니다. 요청 한 번에 발신할 WhatsApp 번호, 고객 전화번호, 템플릿과 변수를 지정합니다.

고객이 답장하면 대화는 다른 대화와 마찬가지로 MonoChat 인박스에 도착합니다. 이 앱에는 별도의 화면이 없으며, 모든 작업이 세 가지 API 엔드포인트로 이루어집니다.

주요 기능

API 호출 한 번. 템플릿 이름과 언어를 지정하고, 헤더, 본문, 버튼, 캐러셀 변수를 고객님의 데이터로 채워 발송합니다.
채팅으로 바로 연결. 발송할 때마다 대화 ID와 MonoChat 내 대화로 이동하는 바로가기 링크가 반환됩니다.
신규 고객도 환영. 전화번호가 아직 고객이 아니면, 보내 주신 이름으로 고객이 생성됩니다.

설치 및 설정

WhatsApp Business 번호를 MonoChat에 연결하고, 인증이 완료되었으며 Meta의 승인을 받은 템플릿이 있는지 확인하세요.
설정 › MonoStore › 앱에서 WhatsApp Template API를 설치하거나 설치 링크 app.monochat.ai/apps/K6u29LpbwCHBozZ8o를 여세요. MonoChat 계정이 없다면 링크에서 먼저 가입할 수 있으며, 앱은 자동으로 설치됩니다.
프로필 › API 토큰에서 API 토큰을 만드세요. 토큰은 한 번만 표시되므로 바로 복사해 두세요.
template/list.js를 호출해 승인된 템플릿과 변수를 확인하세요.
고객 번호와 변수 값을 지정해 template/send.js를 호출하면 첫 템플릿이 발송됩니다.

MonoChat 설정의 MonoStore 앱 목록과 WhatsApp Template API

MonoStore의 WhatsApp Template API 상세 화면과 설치 버튼

노트

각 메시지는 MonoChat에서 보내는 다른 템플릿 메시지와 동일하게 요금이 부과됩니다.
미디어 URL은 WhatsApp이 파일을 가져갈 때까지 접근 가능한 상태로 유지되어야 합니다.
수신에 동의한 고객에게만 발송하세요. 메시지가 차단되거나 신고된 번호는 WhatsApp에서 제한할 수 있습니다.

기능

템플릿 조회

WhatsApp 번호의 승인된 템플릿을 언어, 카테고리, 상태, 변수와 함께 제공하여 시스템에서 발송할 수 있는 항목을 알 수 있습니다.

템플릿 발송

템플릿 이름과 언어로 헤더, 본문, 버튼, 캐러셀 변수와 함께 발송합니다. 값이 빠지면 발송이 중단되므로 반쯤 채워진 메시지가 고객에게 전달되는 일은 없습니다.

상담원에게 배정

상담원의 이메일을 입력하면 해당 상담원 이름으로 대화가 열립니다.

미디어 헤더

유효 시간이 짧은 업로드 자격 증명을 받아 이미지, 동영상 또는 문서를 MonoChat 스토리지에 올리고 그 URL을 템플릿 헤더로 사용합니다.

대화 링크

발송할 때마다 세션 ID, 메시지 ID, MonoChat에서 대화를 여는 링크가 반환됩니다.

명확한 오류 메시지

호출이 실패하면 “Channel not found”, “Variable missing”처럼 무엇이 잘못되었는지 알려 줍니다.

시작하기 전에

WhatsApp Business 번호가 MonoChat에 연결되어 인증되어 있어야 합니다. 채널을 참고하세요.
보내려는 템플릿이 Meta의 승인을 받아야 합니다. 템플릿은 고객에게 먼저 메시지를 보내거나 24시간 창 밖에서 고객에게 연락하는 방법입니다. 템플릿 메시지를 참고하세요.
프로필 › API 토큰에서 만든 API 토큰이 있어야 합니다. API 토큰을 참고하세요.
테넌트 슬러그를 알고 있어야 합니다. MonoChat 주소에서 /tenants/ 뒤에 오는 부분입니다. https://app.monochat.ai/tenants/mybusiness에서 슬러그는 mybusiness입니다.

API 레퍼런스

이 앱에는 별도의 화면이 없습니다. 모든 작업은 세 가지 엔드포인트로 이루어지며, 각각 JSON 본문을 담은 POST 요청입니다.

POST https://app.monochat.ai/api/<slug>/custom-functions/template-app/api/<endpoint>
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

엔드포인트	기능
`template/list.js`	WhatsApp 번호 하나의 템플릿을 변수와 함께 조회합니다.
`template/send.js`	고객에게 템플릿을 발송하고 대화 링크를 반환합니다.
`upload/get-token.js`	헤더 이미지, 동영상, 문서용으로 유효 시간이 짧은 업로드 자격 증명을 발급합니다.

전화번호는 항상 국가 코드를 포함하고 + 없이 입력합니다. 예: 905334445566. 호출이 성공하면 200과 함께 엔드포인트의 데이터가 result 아래에 반환됩니다.

1. 템플릿 조회

POST /api/<slug>/custom-functions/template-app/api/template/list.js

지정한 WhatsApp Business 번호의 모든 템플릿을 이름, 언어 코드, 카테고리, 구성 요소(헤더, 본문, 푸터, 버튼), 변수 유형, 승인 상태와 함께 조회합니다.

필드	필수	설명
`phoneNumber`	예	MonoChat에 등록된 WhatsApp Business 번호. 국가 코드를 포함하고 `+`는 제외합니다.
`options`	아니요	페이지 나누기와 필터, 예: `{ "pagination": { "currentPage": 1, "pageItems": 50 } }`.

POST /api/<slug>/custom-functions/template-app/api/template/list.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566"
}

응답(일부 생략):

{
  "result": {
    "templateMessages": [
      {
        "name": "new_product_announcement",
        "languageCode": "tr-TR",
        "category": "MARKETING",
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "variables": [
              { "type": "IMAGE", "value": null, "exampleValue": "https://.../sample-image.png" }
            ]
          },
          {
            "type": "BODY",
            "text": "Merhaba {{1}}, yeni ürünümüz {{2}} çıktı!",
            "sampleText": "Merhaba [Ayşe], yeni ürünümüz [XYZ Telefon] çıktı.",
            "variables": [
              { "type": "TEXT", "value": null, "exampleValue": "[Ayşe]" },
              { "type": "TEXT", "value": null, "exampleValue": "[XYZ Telefon]" }
            ]
          },
          {
            "type": "FOOTER",
            "text": "Teşekkürler",
            "sampleText": "Teşekkürler"
          }
        ],
        "status": "APPROVED"
      }
    ],
    "options": {
      "pagination": { "totalCount": 12, "currentPage": 1, "pageItems": 12, "totalPages": 1 }
    }
  }
}

읽는 방법:

name: 템플릿을 보낼 때 사용하는 시스템 이름.
languageCode: 발송할 언어.
category: WhatsApp 카테고리(MARKETING, UTILITY, AUTHENTICATION).
components: 템플릿을 구성하는 요소.

구성 요소	내용	설명
`HEADER`	`IMAGE`, `VIDEO`, `DOCUMENT` 또는 텍스트	미디어인 경우 `format`이 제공되며, 변수는 `variables` 아래에 나타납니다.
`BODY`	변수가 포함된 텍스트	`{{1}}`, `{{2}}` 같은 자리 표시자가 있는 메시지 본문.
`FOOTER`	텍스트	보통 변수가 없습니다.
`BUTTONS`	URL, 빠른 답장 등	버튼 텍스트와 변수(있는 경우).

위 예시 템플릿에는 헤더용 이미지 1개와 본문용 텍스트 2개(고객 이름, 제품 이름)가 필요합니다. 푸터는 고정("Teşekkürler")이며 버튼은 없습니다.

2. 템플릿 발송

POST /api/<slug>/custom-functions/template-app/api/template/send.js

승인된 템플릿을 고객에게 발송합니다. 전화번호가 아직 고객이 아니면 고객이 생성되고, 대화가 열리거나(이미 있으면 재사용) 그 안에서 템플릿이 발송됩니다.

필드	필수	설명
`phoneNumber`	예	발신할 WhatsApp Business 번호. MonoChat에 연결되어 인증되어 있어야 합니다.
`templateMessageName`	예	템플릿의 `name`. 목록에서 반환된 값 그대로 입력합니다.
`languageCode`	예	템플릿의 언어. 목록에서 반환된 값 그대로 입력합니다(예: `tr-TR`).
`customerPhoneNumber`	예	고객의 WhatsApp 번호.
`variables`	템플릿에 변수가 있는 경우	템플릿 변수의 값(아래 참고).
`customerFirstName`, `customerLastName`	아니요	고객이 MonoChat에 처음 등록될 때 사용됩니다.
`agentEmailAddress`	아니요	이 이메일의 상담원에게 대화를 배정합니다.

변수. variables 배열의 각 항목에는 type과 parameters 목록이 있으며, 템플릿의 자리 표시자 순서대로 입력합니다.

`type`	`parameters`
`HEADER`	헤더 텍스트 변수, 또는 헤더 이미지·동영상·문서의 공개 URL.
`BODY`	본문의 `{{1}}`, `{{2}}`, … 값을 순서대로.
`BUTTONS`	변수가 있는 각 버튼의 값 하나씩(예: URL 버튼의 동적 부분이나 쿠폰 코드), 버튼 순서대로.
`CAROUSEL`	`parameters` 대신, 캐러셀 카드마다 항목 하나씩 담은 `cards` 배열이며 각 항목에 자체 `components`가 있습니다.

{ "type": "CAROUSEL", "cards": [ { "components": [ { "type": "HEADER", "parameters": ["https://…/1.jpg"] }, { "type": "BODY", "parameters": ["…"] } ] } ] }

값이 빠지면 Variable missing과 함께 발송이 중단되므로 반쯤 채워진 메시지가 고객에게 전달되는 일은 없습니다. FOOTER에는 변수가 거의 없습니다.

POST /api/<slug>/custom-functions/template-app/api/template/send.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566",
  "templateMessageName": "new_product_announcement",
  "languageCode": "tr-TR",
  "customerPhoneNumber": "905306667788",
  "customerFirstName": "Ayşe",
  "agentEmailAddress": "sarah@yourcompany.com",
  "variables": [
    { "type": "HEADER", "parameters": ["https://…/product.jpg"] },
    { "type": "BODY", "parameters": ["Ayşe", "XYZ Phone"] }
  ]
}

응답:

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "…",
    "messageId": "…"
  }
}

url: MonoChat에서 대화를 엽니다. 로그인되어 있고 해당 대화를 볼 수 있는 사용자에게 열립니다.
sessionId: 대화 ID.
messageId: MonoChat 내 메시지 ID. 전달 및 읽음 상태는 다른 메시지와 마찬가지로 채팅에 표시됩니다.

템플릿의 미디어. WhatsApp은 지정한 URL에서 헤더 미디어를 내려받으므로, URL은 유효하고 공개적으로 접근할 수 있어야 합니다. 로그인이 필요한 링크는 작동하지 않습니다. upload/get-token.js로 파일을 업로드했다면 그 응답으로 만든 파일 URL을 사용하세요.

3. 헤더용 미디어 업로드

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js

템플릿 헤더가 이미지, 동영상 또는 문서일 때는 WhatsApp이 내려받을 수 있는 공개 주소가 파일에 필요합니다. 이 엔드포인트는 MonoChat 스토리지에 파일을 올릴 수 있는 유효 시간이 짧은 권한을 발급합니다.

필드	필수	설명
`fileName`	예	확장자를 포함한 파일 이름, 예: `product.jpg` 또는 `promo.pdf`.

파일은 항상 워크스페이스의 chat-assets 폴더에 저장됩니다. key 필드를 보내는 이전 예제도 계속 작동하며, 이 값은 필요하지 않습니다.

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fileName": "product.jpg"
}

응답에는 파일을 올릴 위치와 업로드에 필요한 자격 증명이 담겨 있습니다.

필드	설명
`bucket`, `region`, `path`	파일이 저장될 위치.
`temporaryCredentials`	해당 경로 하나에 대한 업로드 전용 자격 증명으로, 15분 동안 유효합니다.
`baseUrl`	스토리지의 공개 주소. 파일 URL은 `baseUrl` + `/` + `path`입니다.

이 자격 증명으로 아무 S3 클라이언트를 사용해 파일을 바로 업로드한 다음, 템플릿을 발송할 때 그 URL을 HEADER 파라미터로 전달하세요. 매우 큰 파일이나 WhatsApp이 지원하지 않는 형식(일반적인 이미지, 동영상, PDF 형식을 지원합니다)은 실패합니다.

예시: 이미지 헤더가 있는 템플릿

이미지 헤더와 본문 변수 2개(고객 이름, 제품 이름)가 있는 승인된 템플릿 new_product_announcement를 고객에게 보내려 한다고 가정해 봅시다.

템플릿을 조회합니다. WhatsApp 번호로 template/list.js를 호출하고 new_product_announcement를 찾으세요. 구성 요소에는 헤더에 IMAGE 변수 1개, 본문에 TEXT 변수 2개가 있습니다.
이미지를 업로드합니다. { "fileName": "urun.jpg" }로 upload/get-token.js를 호출하고, 반환된 자격 증명으로 파일을 업로드한 뒤 baseUrl과 path로 파일 URL을 만드세요.
템플릿을 발송합니다. 파일 URL을 HEADER 파라미터로, ["Ayşe", "XYZ Telefon"]을 BODY 파라미터로 지정해 template/send.js를 호출하세요({{1}} → Ayşe, {{2}} → XYZ Telefon). 템플릿에 버튼 변수가 있다면 같은 방식으로 BUTTONS 항목을 추가하면 됩니다.
채팅을 엽니다. 응답의 url로 대화가 열리며, 고객이 답장하면 대화는 MonoChat 인박스에서 이어집니다.

오류

호출이 실패하면 오류 상태와 무엇이 잘못되었는지 알려 주는 메시지가 반환됩니다. 이 메시지를 시스템에 기록하고, 필요하면 사용자에게 알기 쉬운 메시지를 보여 주세요.

메시지	원인
`phoneNumber field is required`	`phoneNumber` 없이 `template/list.js`를 호출했습니다.
`phoneNumber, templateMessageName, customerPhoneNumber fields are required`	`template/send.js`의 필수 필드가 누락되었습니다.
`Channel not found`	`phoneNumber`가 워크스페이스의 WhatsApp 번호가 아닙니다.
`Channel is not verified`	WhatsApp 번호는 연결되어 있지만 인증되지 않았습니다.
`Template message not found`	해당 번호에 그 이름과 언어의 승인된 템플릿이 없습니다. 철자와 `languageCode`를 확인하세요.
`Template message is not approved`	템플릿은 있지만 Meta의 승인을 받지 않았습니다.
`Variable missing: …`	`variables`가 템플릿과 맞지 않습니다. 예를 들어 템플릿은 본문 값 2개가 필요한데 1개만 보냈습니다.
`Agent user not found`	`agentEmailAddress`의 이메일을 가진 상담원이 없습니다.
`Customer Channel not found`	고객의 WhatsApp ID를 생성하거나 찾을 수 없습니다.

확인할 수 있는 HTTP 상태 코드:

401 Unauthorized: Authorization: Bearer <API_TOKEN> 헤더가 없거나 토큰이 잘못되었거나 만료되었습니다. 계정의 유효한 토큰을 사용하세요.
403 Forbidden: 토큰에 이 워크스페이스 또는 앱에 대한 권한이 없습니다. 예를 들어 테넌트 슬러그가 잘못된 경우입니다.
404 Not Found: 엔드포인트 주소가 잘못되었습니다. 전체 경로 /api/<slug>/custom-functions/template-app/api/...를 확인하세요.
500 Internal Server Error: MonoChat 또는 WhatsApp 제공업체의 예기치 않은 문제이거나 WhatsApp 측의 거부(WhatsApp을 사용하지 않는 번호, 고객의 차단, 품질 또는 발송 한도 제한)입니다. 잠시 후 다시 시도하고, 계속되면 MonoChat 지원팀에 문의하세요.

스크린샷

CRM, ERP, 이커머스 시스템에서 MonoChat을 통해 API 호출 한 번으로 승인된 WhatsApp 템플릿 발송

승인된 WhatsApp 템플릿과 변수 목록

새 번호로 템플릿을 발송하면 고객이 자동으로 생성됩니다

하나의 템플릿을 여러 언어로 발송

이미지, 동영상, 문서, PDF 헤더가 있는 템플릿

자주 묻는 질문