Kakao i Agent::Service Agent 등록::AIID 발급

페이지 이동경로

AIID 발급

AI Instance ID(이하 AIID)는 카카오 AI 음성 서비스를 사용하는 입/출력 장치의 Endpoint ID로서 각각의 Instance를 구별하는 식별자입니다. AIID 발급은 Curl 또는 Postman과 같은 다양한 프로그램에서 수행할 수 있으며, 진행하는 작업하는 순서는 동일합니다. 본 가이드에서는 Curl을 사용한 기준으로 설명합니다.

AIID 발급 시, 디바이스 또는 애플리케이션의 장치 식별자(유일한 값)가 존재하는 경우에는 한 명의 사용자가 하나의 계정으로 여러 디바이스 또는 애플리케이션에 접근하기 위해 추가적으로 AIID를 생성할 수 있습니다.
각 디바이스 또는 애플리케이션 별로 추가 AIID를 발급 받고 사용할 수 있습니다. 반면에 장치 식별자(유일한 값)가 없는 경우에는 발급 요청 시마다 새로운 AIID 값이 반환되는 특성이 있기 때문에 인증 정보가 만료되지 않은 경우라면 AIID를 최대한 오래 사용하는 것을 원칙으로 합니다.

AIID가 변경되면 다른 디바이스 또는 애플리케이션으로 인식되므로 디바이스 또는 애플리케이션에 대한 설정값이 유지되지 않고, 연속된 대화도 진행할 수 없습니다.

주의
회원 탈퇴 또는 서비스 탈퇴 시에 관련된 AIID는 모두 파기됩니다.

발급 절차

  1. 인증에서 획득한 Access Token(access_token)과 사용자 ID(app_user_id)를 사용하여 다음의 명령어를 완성합니다.

    코드예제CURL 명령어

      curl -X POST http://sandbox-app.i.kakao.com/api/client/auth/v0/addInstance?device_id=XXXXX \
        -H 'Authorization: XBearer 123abcdefghijklmnopqrstuvwxyz1116' \
        -H 'Content-Type: application/json' \
        -H 'KakaoI-Agent: KVS/1.0 (Linux; Android 24 7.0; Redmi Note 4/NRD90M; AIID -)
        com.cryyull.sancha_tm1k.dev/1.0/1 SDK/1.1.1' \ -H 'KakaoI-User: AU 1116’
    

  2. AIID 발급 CURL 명령어에 대한 응답에서 AIID(id_string)를 확인합니다. 코드예제AIID 정보 확인

    {
        "id_string":"1s2gMunt",
        "id_number":"KAI12864546678681191116",
        "application_type":{
            "package_name":"com.kep.agent_tm1k.dev"
            "platform":1
        },
        "status":0,
        "created_at":1550046233623,
        "_code":200,
        "_message":"OK"
    }
    

AIID 발급 API

Request

API 호출 방식
메서드 요청 URL
POST http://sandbox-app.i.kakao.com/api/client/auth/v0/addInstance

Request Syntax

코드예제AIID 발급 Request Syntax

    curl -X POST http://sandbox-app.i.kakao.com/api/client/auth/v0/addInstance?device_id=XXXXX \
    -H 'Authorization: XBearer 123abcdefghijklmnopqrstuvwxyz1116' \
    -H 'Content-Type: application/json' \
    -H 'KakaoI-Agent: KVS/1.0 (Linux; Android 24 7.0; Redmi Note 4/NRD90M; AIID -)
    com.cryyull.sancha_tm1k.dev/1.0/1 SDK/1.1.1' \ 
    -H 'KakaoI-User: AU 1116'

Path Parameters

Path Parameters
파라미터 타입 필수 여부 설명
device_id String 선택 디바이스 ID
- 식별 번호가 존재할 경우 기입

Request Header

AIID 발급 Request Header
파라미터 타입 필수 여부 설명
Authorization String 필수 사용자 인증을 위한 Access Token
Bearer: Prefix로 삭제 금지이며, 뒤에 한 칸 공백 유지
XBearer: xOAuth 방식
KakaoI-Agent String 필수 AIID 발급을 위한 에이전트 정보
- KakaoI-Agent (User-Agent도 가능하나 KakaoI-Agent 사용을 권장)
- AIID -) 이후 패키지명(package_name) 정의 필요
- package_name의 값은 안드로이드 애플리케이션 패키지명이나 iOS 앱의 번들 ID를 사용
KakaoI-User String 필수 카카오 i 사용자 정보(헤이카카오 앱의 사용자 ID)
- KakaoI App User ID (ex. AU #####)
- AU 부분은 Prefix로 삭제 금지이며, Prefix 뒤 한 칸 공백 유지
- xOAuth 토큰을 사용 시, appUserId 대신 resource_owner_id 값 사용
주의
Request Header 정보 중 Bearer(또는 XBearer)와 AU는 Prefix로서 절대 삭제하지 마시고, Prefix 뒤에는 반드시 한 칸 공백을 유지하십시오.

Response

AIID 발급 Response Elements
필드 타입 필수 여부 설명
id_string String 필수 AIID(AI Instance ID) 값
id_number String 필수 AIIN(AI Instance Number) 값
created_at String 필수 생성 일시
Object 필수 AIID가 등록된 애플리케이션 정보
package_name String 필수 생성할 애플리케이션의 패키지명 또는 번들 ID
platform Integer 필수 애플리케이션의 플랫폼 정보
1: 안드로이드(Android)
2:  iOS
status Integer 필수 상태 정보
_code Integer 필수 API 동작 결과 코드
200: 성공
400: 요청 실패(주로 파라미터 입력 오류)
401: 인증 오류(주로 토큰 만료)
481: 업그레이드 필요
482: 미승인 약관 동의 > Connect Web 가입
483: 미등록 사용자 > Connect Web 가입
485: 미등록 애플리케이션 > AIID 발급
500: 서버 내부 오류
503: 서비스 점검 중
_message String 필수 API 동작결과 메시지
안내
_code에서 발생하는 오류 코드 값의 자세한 해결 방안은 Troubleshooting 문서를 참고하시기 바랍니다.
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 documentation@kakaoenterprise.com 으로 제보해주세요.