이 문서는 카카오톡 메시지 API 또는 카카오톡 공유 API로 보낼 메시지를 메시지 템플릿 도구를 사용해 사용자 정의 템플릿으로 구성하는 방법을 설명합니다. 각 항목에 대한 자세한 내용은 이해하기에서 확인할 수 있습니다.

메시지 템플릿 도구를 사용하면 사용자 인터페이스에서 메시지 템플릿을 쉽게 만들 수 있게 해주며, 개발 지식이 없어도 UI에서 템플릿을 생성할 수 있습니다. 메시지 발송 API를 호출할 때 템플릿 ID만 전달하면 해당 템플릿으로 메시지를 보낼 수 있습니다.

1. [도구] > [메시지 템플릿]에서 사용할 앱을 선택합니다.
   • 템플릿은 앱별로 관리되어 다른 앱의 템플릿 ID로 메시지를 보낼 수 없습니다.
2. 템플릿 종류별 구성 요소 지원 여부를 참고해 사용할 메시지 템플릿을 선정 후 [메시지 템플릿 추가] 선택해 새 템플릿을 추가합니니다.
3. 메시지 템플릿을 설정합니다. 네이티브 앱 스킴 선택 시 주의 사항을 함께 확인합니다. 사용자 인자를 사용하면 동적인 메시지를 구성할 수 있습니다.
4. 카카오톡 메시지 API 또는 카카오톡 공유 API 호출 시, template_id 값으로 생성한 템플릿 ID를 전달해 API를 호출합니다.

사용자 정의 템플릿으로 메시지 발송 시 필요한 템플릿 ID는 메시지 템플릿 설정 화면의 [B] 또는 [C] 영역에서 확인할 수 있습니다.

메시지 템플릿 목록

[A] 앱 정보: 현재 선택된 앱 정보 표시, 앱 이름 옆 목록 아이콘을 눌러 다른 앱 선택 가능
[B] 메시지 템플릿 추가: 선택한 앱에 새 메시지 템플릿 추가
[C] 검색 및 필터링 영역: 대상을 입력하거나 설정 상태나 조건(템플릿 제목, 메시지 제목, 본문, 버튼명 등)을 선택하여 원하는 템플릿만 모아보기 가능
[D] 템플릿 목록: 선택한 앱에 등록된 전체 템플릿 목록, 템플릿 선택 시 상세 설정 페이지로 이동
[E] 더보기 버튼: 해당 템플릿을 복사하거나 삭제

메시지 템플릿 도구 상세 화면

[A] 앱 정보: 현재 선택된 앱 정보, 앱 이름 옆 목록 아이콘을 눌러 다른 앱 선택 가능
[B] 템플릿 목록: 선택한 앱에 등록된 전체 템플릿 목록, 템플릿 선택 시 상세 설정 페이지로 이동
[C] 메시지 템플릿 정보: 템플릿 ID와 종류 표시, 템플릿 수정 사항을 저장하거나 템플릿 삭제
[D] 검색 결과: 검색 전 메시지 템플릿 목록으로 이동
[E] 공통 설정: 모든 템플릿에 공통으로 적용되는 설정
[F] 네이티브 앱 스킴: 템플릿에서 사용할 네이티브 앱 커스텀 URL 스킴 선택, 네이티브 앱 스킴 선택 시 주의 사항 확인 필요
[G] 구성 요소별 설정: 각 구성 요소 상세 설정, 메시지 타입에 따라 설정할 수 있는 구성 요소 상이 (참고: 종류별 구성 요소 지원 여부)
[H] 미리보기: 현재 설정을 반영한 메시지 미리보기, 각 구성 요소 클릭 시 해당 설정 화면으로 이동함
[I] 저장: 수정 사항 저장, [C]의 [저장]과 동일한 기능

메시지 템플릿 종류에 따라 지원하는 구성 요소가 다릅니다. 아래는 템플릿 종류별로 설정할 수 있는 구성 요소입니다. 구성 요소 이름을 눌러 상세 정보를 확인할 수 있습니다. 이 표를 참고해 어떤 템플릿을 사용할 지 결정합니다.

메시지 템플릿 도구에서 구성 요소별로 설정할 수 있는 항목을 안내합니다.

템플릿 종류에 상관 없이 공통으로 제공되는 설정입니다.

공통 설정에서 선택하는 네이티브 앱 스킴은 표시 [태그]에 따라, 같은 값이어도 기본 네이티브 앱 스킴 변경 시 동작이 서로 다릅니다. 아래 태그별 설명을 참고합니다.

• [기본 네이티브 앱 정보]: 기본 네이티브 앱 스킴을 변경하면 값도 함께 변경됨, 기본 스킴 설정과 연동된 템플릿을 구성하는 경우 사용
• [앱 키 이름]: 기본 네이티브 앱 스킴 변경 여부와 상관없이 고정된 값 유지, 기본 스킴 설정과 상관없이 고정된 템플릿을 구성하는 경우 사용

메시지 구성 요소 중 링크를 설정합니다. 링크 설정은 크게 세 가지로 나뉩니다.

• 공통 링크: 웹 페이지나 앱 링크를 추가할 수 있는 영역에 공통적으로 적용할 링크 정보
• 컴포넌트 별 링크 상세: 특정 구성 요소에 적용할 링크 정보
• 출처 링크: 메시지 하단의 앱 기본 정보에 추가할 링크 정보, 메시지 템플릿 도구로 등록한 템플릿에서만 편집 가능, 앱 이름과 아이콘은 수정 불가

각 링크에 설정 가능한 항목은 아래와 같습니다. 링크 정보의 우선순위와 실행 조건은 링크를 참고합니다.

링크 설정 상세 화면

메시지 구성 요소 중 콘텐츠의 일부에 해당하는 설정입니다. 이미지를 모두 삭제하면 메시지에서 이미지 영역을 제외할 수 있습니다.

이미지 아래의 영역의 이미지와 메시지 제목/본문 사이에 나타나는 프로필 형태의 정보를 설정합니다. 마치 프로필의 인물이나 서비스가 정보를 게시한 것처럼 보이게 할 수 있습니다.

피드 메시지와 리스트 메시지에서 상단에 표시할 제목 영역을 설정합니다. 피드 메시지는 프로필과 헤더 중 하나만 사용할 수 있습니다.

제목, 카테고리, 이미지로 구성된 하나의 아이템 정보를 입력할 수 있습니다.

각 아이템의 정보로, 최대 5개까지 설정할 수 있습니다.

메시지 구성 요소 중 콘텐츠의 일부에 해당하며, 영역에 글자로 출력되는 제목과 설명을 설정합니다. 메시지 제목/본문은 제목 두 줄, 설명 두 줄까지만 출력됩니다. 두 줄이 넘어가는 글은 잘려 보일 수 있습니다.

메시지 구성 요소 중 소셜에 해당하는 설정입니다. 마치 메시지로 공유한 내용이 많은 사용자들의 관심과 호응을 받은 것처럼 보이게 할 수 있고, 사용자 인자를 활용해 실제 사용자들의 좋아요나 댓글 수를 반영할 수도 있습니다.

소셜 영역에는 최대 3가지 정보만 출력할 수 있습니다. 값을 입력하지 않은 항목이 소셜 영역에서 제외됩니다. 3개를 초과하는 항목이 입력됐을 경우, 우선 노출순위는 좋아요 > 댓글 > 공유 > 조회 > 구독자순입니다.

메시지 구성 요소 중 리스트에 해당하며, 리스트 영역은 여러 개의 아이템을 목록 형태로 메시지에 담아 보여줍니다. 최대 5개의 아이템을 목록에 담을 수 있습니다. 아이템은 최소 1개 이상 존재해야 합니다.

커머스 메시지의 상품 이름 및 가격 정보를 설정합니다. 메시지 구성 요소 중 커머스의 하위 항목인 commerce에 해당합니다. 이미지 > 프로필 > 상품 설명 순서로 위치합니다.

커머스 메시지의 상품 설명을 설정하는 메뉴입니다. 메시지 구성 요소 중 커머스의 description에 해당합니다.

메시지 구성 요소 중 버튼에 해당합니다. 사용자 정의 템플릿에는 1~2개의 회색 버튼을 추가할 수 있습니다. 버튼은 사용자를 웹 페이지 또는 앱으로 이동시키기 위한 용도로 사용합니다.

사용자 인자는 메시지 템플릿에서 동적으로 값을 변경할 수 있는 변수입니다. 메시지 템플릿을 만들 때 ${KEY} 형식으로 변수를 지정해두면, 메시지를 보낼 때마다 각 사용자에게 맞는 값으로 대체할 수 있습니다.

사용자 인자를 사용하면 하나의 템플릿으로 여러 사용자에게 각각 다른 내용의 메시지를 보낼 수 있습니다. 예를 들어 아래와 같은 상황에서 사용자 인자를 활용할 수 있습니다.

• 각 사용자의 이름이나 닉네임을 메시지에 포함할 때
• 주문번호, 배송 상태 등 사용자별로 다른 정보를 안내할 때
• 사용자별 맞춤 링크나 이미지를 설정할 때
• 메시지의 버튼 텍스트나 정렬을 동적으로 변경할 때

메시지 템플릿에서 사용자 인자를 활용하는 방법은 아래 두 가지가 있습니다.

• 직접 사용자 인자 입력하기
• 사용자 인자 옵션 사용하기

메시지 제목/본문이나 헤더와 같은 텍스트 입력란에 직접 ${KEY} 형식으로 사용자 인자를 입력해 사용합니다.

1. 텍스트 입력란에 ${KEY} 형식으로 사용자 인자를 입력합니다. 영문 대소문자, 숫자, 언더바(_)만 사용할 수 있습니다.
   • 예: ${user_name}, ${order_id} 등
2. 메시지 발송 API 호출 시 template_args에 각 키에 대응하는 모든 값을 ${} 문구를 제외한 key:value 형태로 전달합니다. 누락된 항목은 ${KEY} 형식으로 메시지에 그대로 노출되므로 주의합니다.
   • 예: {"template_args": {"user_name": "홍길동", "order_id": "A001-23948"}}
3. URL 쿼리 파라미터에 사용자 인자를 사용하는 경우, template_args의 value에 해당하는 값에 폼 URL 인코딩(application/x-www-form-urlencoded)을 적용해야 합니다.

템플릿 도구에서 [메시지 본문]에 아래와 같이 사용자 인자를 사용해 템플릿을 구성합니다.

${user_name}님, 주문하신 상품이 배송되었습니다!
주문번호: ${order_id}

메시지 발송 API 호출 시 아래와 같이 사용자 인자 값을 함께 전달합니다. 아래 예시는 나에게 사용자 정의 템플릿으로 메시지 발송 API 예시입니다.

curl -v -X POST "https://kapi.kakao.com/v2/api/talk/memo/send" \
  -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "template_id=12345" \
  -d 'template_args={
        "user_name": "홍길동",
        "order_id": "A001-23948"
      }'

사용자는 아래와 같은 메시지를 받을 수 있습니다.

홍길동님, 주문하신 상품이 배송되었습니다!
주문번호: A001-23948

아래 키(Argument key)는 웹페이지 스크랩을 위해 이미 할당되어 있어 사용자 인자 키로 사용할 수 없습니다. 스크랩 메시지를 참고합니다.

• ${SCRAP_IMAGE}
• ${SCRAP_IMAGE_WIDTH}
• ${SCRAP_IMAGE_HEIGHT}
• ${SCRAP_IMAGE_DURATION}
• ${SCRAP_TITLE}
• ${SCRAP_DESCRIPTION}
• ${SCRAP_HOST}
• ${SCRAP_REQUESTED_URL}

이미지, 버튼 정렬 등 구성 요소 설정 화면에서 [사용자 인자] 옵션을 제공하는 경우, 해당 옵션을 선택하여 사용할 수 있습니다.

1. 구성 요소 설정 화면에서 [사용자 인자] 옵션을 선택합니다.
2. 시스템이 제공하는 기본 키를 사용하거나 원하는 키로 변경합니다.
   • 예: 버튼 정렬의 경우 기본값 ${BUT}이 제공됨
   • 버튼 정렬 예시: ${BUT}=0(가로 정렬), ${BUT}=1(세로 정렬)
3. 메시지 발송 API 호출 시 template_args 필드에 해당 키와 값을 전달합니다.

아래는 버튼 정렬을 세로로 변경하는 API 요청 예시입니다.

curl -v -X POST "https://kapi.kakao.com/v2/api/talk/memo/send" \
  -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "template_id=12345" \
  -d 'template_args={
        "BUT": "1",
      }'