메시지 연동, 여기서 시작하세요.

이용 안내

센드고 연동은 키를 발급받고 → 토큰을 얻고 → 발송을 요청하는 세 단계입니다. 이 문서는 그 순서만 다룹니다. 엔드포인트별 파라미터는 API, 언어별 설치·예제는 SDK 문서에 있습니다.

무엇을 연동할 수 있나

채널	엔드포인트	미리 준비할 것
문자 (SMS · LMS · MMS)	POST /api/v2/messages/send	발신번호 등록
알림톡	POST /api/v2/notices/send	카카오 발신프로필 + 승인된 템플릿
브랜드 메시지	POST /api/v2/brand-messages/send	카카오 발신프로필 + 사용 신청
짧은주소	POST /api/v2/short-urls	없음
크레딧 조회	GET /api/v2/credits	없음

1. 준비물

연동을 시작하기 전에 콘솔에서 끝내 두어야 하는 것들입니다. 이 준비가 빠지면 토큰은 발급되지만 발송 요청이 거절됩니다.

• 기업 회원 전환 — 알림톡·브랜드 메시지는 기업 회원 전용입니다. 문자만 보낼 경우에는 필요하지 않습니다.
• 발신번호 등록 — 발신번호 관리에서 통신서비스 이용증명원으로 등록합니다. 승인 전에는 발송에 사용할 수 없습니다.
• 카카오 발신프로필 — 알림톡·브랜드 메시지를 보내려면 카카오톡 > 발신프로필 관리에서 채널을 연결합니다.
• 알림톡 템플릿 승인 — 카카오 검수에 영업일 기준 2~3일이 걸립니다. 승인된 템플릿만 발송할 수 있습니다.
• 크레딧 충전 — 잔액이 없으면 발송이 실패합니다. 잔액은 GET /api/v2/credits 로도 확인할 수 있습니다.

2. 키 발급

연동하기 > 앱 · API 연동 > 내 앱 · API 키에서 서비스별 앱을 등록합니다. 앱의 액세스 키와 시크릿 키는 샌드고 접속 인증에 사용하고, 발신번호 ID·카카오 채널 프로필 키는 보낼 메시지의 발신자를 지정할 때 사용합니다. 발신번호와 채널은 같은 계정·조직의 앱에서 함께 사용합니다.

• 신규 앱은 기본으로 자동 승인되어 바로 API 인증에 사용할 수 있습니다. 앱을 선택하면 시크릿 키를 확인·복사할 수 있습니다. 기본 화면에서는 숨겨져 있으며 보기를 눌러 확인합니다.
• 문제가 발견된 앱은 사용이 중지되며 이미 발급한 토큰도 차단됩니다. 발신번호·기업·템플릿 등의 별도 승인 요건은 그대로 적용됩니다.
• IP 허용목록을 함께 등록하는 것을 권합니다. 키가 유출되어도 등록된 IP 밖에서는 쓸 수 없습니다.
• 키는 서버에만 두세요. 브라우저나 모바일 앱에 넣으면 누구나 꺼내 볼 수 있습니다.

3. 토큰 발급

v2 는 서명 기반 Bearer 토큰을 씁니다. 액세스 키와 시크릿 키를 : 로 이어 Base64 로 인코딩해 보냅니다.

curl -X POST https://api.sendgo.io/api/v2/token \
  -H "Authorization: Basic $(printf '%s:%s' "$ACCESS_KEY" "$SECRET_KEY" | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded"

토큰은 sgv2.{payload}.{signature} 형태이며 24시간 유효합니다.

• 요청마다 새로 발급하지 말고 만료 전까지 재사용하세요.
• v1 토큰과는 호환되지 않습니다. v2 엔드포인트에는 v2 토큰만 통과합니다.

4. 첫 발송

발급받은 토큰을 Authorization: Bearer 로 넣어 발송을 요청합니다.

curl -X POST https://api.sendgo.io/api/v2/messages/send \
  -H "Authorization: Bearer $V2_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderKey": "9cd5460b-6458-4edc-9b11-c26d3013c340",
    "campaignType": "MESSAGE",
    "messageType": "SMS",
    "scheduleType": "DIRECTLY",
    "content": "안녕하세요. #{name}님, 첫 발송 테스트입니다.",
    "contacts": [{ "contact": "01011112222", "name": "홍길동" }]
  }'

응답의 traceId 는 문의할 때 그 요청을 특정하는 값입니다. 로그에 남겨 두세요.

발송은 접수 성공과 전달 성공이 다릅니다. 위 응답은 접수까지만 보장하고, 실제 전달 결과는 webhooks 로 받거나 GET /api/v2/messages/{campaign_id} 로 조회합니다.

5. SDK 로 줄이기

토큰 캐싱·서명·재시도를 직접 구현할 필요는 없습니다. 20개 언어·프레임워크용 SDK가 같은 일을 대신합니다.

use Sendgo\Php\Sendgo;

$sendgo = new Sendgo([
    'access_key'     => $_ENV['SENDGO_ACCESS_KEY'],
    'secret_key'     => $_ENV['SENDGO_SECRET_KEY'],
    'sms_sender_key' => $_ENV['SENDGO_SMS_SENDER_KEY'],
    'api_version'    => 'v2',
]);

$sendgo->sms->sendSms([
    'content'  => '안녕하세요. 첫 발송 테스트입니다.',
    'contacts' => [['contact' => '01011112222']],
]);

설치 명령과 언어별 예제는 SDK 문서를 보세요.

자주 막히는 지점

증상	원인
토큰 발급이 401	키를 : 로 잇지 않고 각각 인코딩했거나, v1 키로 v2 토큰을 요청
발송이 403	요청 IP 가 허용목록에 없음
발신번호 오류	등록만 하고 승인 전이거나, 다른 계정의 발신번호
알림톡 템플릿 오류	승인되지 않은 템플릿, 또는 본문이 승인된 템플릿과 한 글자라도 다름
문자가 장문으로 나감	본문이 90byte 초과. 긴 링크는 짧은주소로 줄이면 단가를 유지할 수 있음

그다음 볼 문서

• API — 엔드포인트별 요청·응답 필드와 에러 코드 전체
• SDK — 언어·프레임워크별 설치와 예제
• 이용내역 — 실제로 오간 API 요청과 응답 기록
• openapi.yaml — 코드 생성기·API 클라이언트에 그대로 넣을 수 있는 명세
• llms.txt — AI 코딩 도구에 문서 전체를 물려줄 때 쓰는 진입점