@teamlearners/clawops

ClawOps Node.js SDK

ClawOps Voice API의 공식 Node.js/TypeScript 라이브러리입니다.

설치

# REST API SDK만 사용
npm install @teamlearners/clawops

# AI Agent 포함 (필요한 프로바이더를 함께 설치)
npm install @teamlearners/clawops ws openai                          # OpenAI Realtime 모드
npm install @teamlearners/clawops ws @google/genai                   # Gemini Realtime 모드
npm install @teamlearners/clawops ws @deepgram/sdk openai elevenlabs # Pipeline 모드 (OpenAI LLM)
npm install @teamlearners/clawops ws @deepgram/sdk @anthropic-ai/sdk elevenlabs # Pipeline 모드 (Anthropic LLM)

AI Agent (음성 에이전트)

ClawOpsAgent를 사용하면 한 줄로 인바운드 전화를 AI로 처리할 수 있습니다. ngrok 없이 WebSocket 역방향 연결로 동작합니다.

import { ClawOpsAgent, OpenAIRealtime } from '@teamlearners/clawops/agent';

const agent = new ClawOpsAgent({
  from: '07012341234',
  session: new OpenAIRealtime({
    systemPrompt: '친절한 상담원입니다. 고객의 질문에 답변해주세요.',
    voice: 'marin',
    language: 'ko',
  }),
});

agent.tool('check_order', '주문 상태를 확인합니다.', { orderId: { type: 'string' } }, async ({ orderId }) => {
  return '배송 완료';
});

agent.on('call_start', async (call) => {
  console.log(`통화 시작: ${call.fromNumber} -> ${call.toNumber}`);
});

await agent.serve(); // Ctrl+C로 종료

Outbound 발신 Prewarm (낮은 첫 음성 latency)

outbound 통화에서 상대 응답 직후 첫 음성까지의 지연을 줄이기 위해, ClawOpsAgent 는 control WS 의 call.outbound_ready 이벤트 수신 즉시 LLM WebSocket 을 미리 연결하고 첫 audio delta 를 메모리에 누적한다 (prewarm + first-audio prebuffer). media WS 가 연결되면 누적된 chunk 를 flush 하여 사용자가 첫 음성을 빠르게 듣게 한다.

const agent = new ClawOpsAgent({
  from: '07012341234',
  session: new OpenAIRealtime({ systemPrompt: '...' }),
  prewarmEnabled: true, // default true
});

비용/효과 검증 단계에서는 prewarmEnabled: false 로 비활성화할 수 있다. 동작 측정은 [PREWARM-T] 로그 마커(start / done / failed / attach / first-audio)를 grep 하여 elapsed 를 계산한다.

한계 / 비목표

• 동시 outbound 통화 1건 가정 — ClawOpsAgent 1 인스턴스의 session 객체는 prewarm 시 단일 BufferingCall 을 공유한다. 같은 인스턴스로 동시 outbound 통화를 발신하면 prewarm race 가 발생할 수 있다. 다중 동시 outbound 가 필요하면 통화별로 별도 ClawOpsAgent 인스턴스를 사용하거나, session factory 패턴 도입이 필요하다 (후속 과제).
• Session 타입별 효과 차이 — Realtime (OpenAI / Gemini) 에서 LLM WS handshake + session.update 가 prewarm 으로 숨겨지므로 latency 절감 효과가 가장 크다. 반면 PipelineSession 은 STT / LLM / TTS 가 lazy 연결되므로, prewarm 단계에서는 STT 루프 기동과 greeting kickoff 정도만 선행되어 latency 절감 효과가 제한적이다.

Call Transfer (통화 전환)

AI가 통화 중 다른 번호로 전환할 수 있습니다. Blind(즉시)와 Warm(안내 후) 모드를 지원합니다.

import { ClawOpsAgent, OpenAIRealtime, BuiltinTool } from '@teamlearners/clawops/agent';

const agent = new ClawOpsAgent({
  from: '07012341234',
  session: new OpenAIRealtime({
    systemPrompt: '고객 문의를 처리하고, 필요하면 상담원에게 전환하세요.',
  }),
  builtinTools: [BuiltinTool.HANG_UP, BuiltinTool.TRANSFER_CALL],
});

// 코드에서 직접 전환도 가능
agent.on('call_start', async (call) => {
  if (shouldTransfer) {
    await call.transfer('01012345678', { mode: 'warm', whisper: 'VIP 고객입니다.' });
  }
});

await agent.serve();

MCP 서버 연동

MCP 서버를 연결하여 AI에게 외부 도구를 제공할 수 있습니다.

npm install @teamlearners/clawops ws @modelcontextprotocol/sdk

import { ClawOpsAgent, OpenAIRealtime, mcpServerStdio, mcpServerHTTP } from '@teamlearners/clawops/agent';

const agent = new ClawOpsAgent({
  from: '07012341234',
  session: new OpenAIRealtime({
    systemPrompt: '상담원입니다.',
  }),
  mcpServers: [
    mcpServerStdio('npx', { args: ['@modelcontextprotocol/server-google'], env: { GOOGLE_API_KEY: '...' } }),
    mcpServerHTTP('https://my-mcp-server.com', { headers: { Authorization: 'Bearer token' } }),
  ],
});

await agent.serve(); // Ctrl+C로 종료

MCP 서버는 전화가 올 때마다 자동으로 시작되고, 통화 종료 시 정리됩니다. MCP 서버가 제공하는 도구는 agent.tool()로 등록한 도구와 함께 세션에 자동 등록됩니다.

OpenTelemetry Tracing

통화 흐름, MCP 도구 호출, LLM 세션을 OpenTelemetry로 추적할 수 있습니다.

npm install @teamlearners/clawops ws @opentelemetry/api @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-grpc

import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc';

const provider = new NodeTracerProvider();
provider.addSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter()));
provider.register();

import { ClawOpsAgent, OpenAIRealtime, setTracingConfig } from '@teamlearners/clawops/agent';

setTracingConfig({ enabled: true, serviceName: 'my-call-center' });

const agent = new ClawOpsAgent({
  from: '07012341234',
  session: new OpenAIRealtime({ systemPrompt: '상담원입니다.' }),
});

Span 계층:

• call → mcp.connect → llm.session → tool.call → mcp.call_tool

자세한 사용법은 Agent 문서 를 참고하세요. (Tool, 이벤트, 통화 녹음, 파이프라인 모드, 커스텀 제공자, MCP 연동, Tracing 등)

REST API 사용법

import ClawOps from '@teamlearners/clawops';

const client = new ClawOps({
  apiKey: 'sk_...',          // 또는 CLAWOPS_API_KEY 환경변수 사용
  accountId: 'AC1a2b3c4d',   // 또는 CLAWOPS_ACCOUNT_ID 환경변수 사용
});

통화 (Calls)

// 발신 전화 생성
const call = await client.calls.create({
  to: '01012345678',
  from: '07052358010',
  url: 'https://my-app.com/twiml',
  statusCallback: 'https://my-app.com/status',
  statusCallbackEvent: 'initiated ringing answered completed',
});
console.log(call.callId);

// 음성사서함 감지(AMD) — Enable=결과만 통보(통화 계속), Hangup=사서함이면 자동 종료
const amdCall = await client.calls.create({
  to: '01012345678',
  from: '07052358010',
  url: 'https://my-app.com/twiml',
  machineDetection: 'Enable',
});
// 통화 종료 후 결과 확인: human(사람) / machine(자동응답기) / unknown(판정 불가)
const done = await client.calls.get(amdCall.callId);
console.log(done.answeredBy);
// statusCallback 을 설정했다면 completed 이벤트 payload 의 AnsweredBy 로도 통보됩니다.

// 통화 목록 조회 (페이지네이션)
const page = await client.calls.list({ status: 'completed', page: 0, pageSize: 20 });
for (const call of page) {
  console.log(call.callId, call.status);
}

// 모든 통화를 자동으로 순회
for await (const call of (await client.calls.list()).autoPagingIter()) {
  console.log(call.callId);
}

// 특정 통화 조회
const detail = await client.calls.get('CAabcdef1234567890');

// 연결 실패 사유 확인 — status가 'failed' 인 경우는 결번·망 오류·시스템 오류를 모두 포함하는
// 대분류라, 다시 걸어도 소용없는 번호를 가려내려면 hangupCause 를 봅니다.
const DO_NOT_RETRY = ['invalid_number', 'number_changed', 'incompatible_destination'];
if (detail.status !== 'completed') {
  if (DO_NOT_RETRY.includes(detail.hangupCause ?? '')) {
    console.log(`결번 — 목록에서 제외: ${detail.to}`); // hangupCauseQ850=1, sipResponseCode=404
  } else if (detail.hangupSource === 'app' || detail.hangupSource === 'system') {
    console.log('ClawOps 측 오류 — 재시도');
  } else {
    console.log(`일시적 사유(${detail.hangupCause}) — 나중에 재시도`);
  }
}

// 통화 종료
await client.calls.update('CAabcdef1234567890', { status: 'completed' });

// 통화 전사 상태 조회 (completed 시 segments 까지 inline)
const state = await client.calls.getTranscript('CAabcdef1234567890');
if (state.status === 'completed') {
  for (const seg of state.segments ?? []) {
    console.log(`[${seg.speaker}] ${seg.text}`);
  }
} else if (state.status === 'not_requested') {
  // 조직 설정 off 거나 아직 요청 안 된 상태 — 명시 요청 (사용량 과금)
  await client.calls.requestTranscript('CAabcdef1234567890');
}

// 통화 요약 상태 조회 (completed 시 resultJson 까지 inline)
const summary = await client.calls.getSummary('CAabcdef1234567890');
if (summary.status === 'completed') {
  console.log(summary.resultJson); // { coreSummary, decisions, followUps, sentiment }
}

통화 녹음 (Recordings)

콘솔에서 들리는 것과 동일한 서버측 MixMonitor 원본(WAV PCM 16bit mono 8kHz)을 다운로드합니다. SDK 측 mix.wav가 아닌 서버에서 합성된 파일이라 싱크/볼륨이 정상입니다.

import { writeFile } from 'node:fs/promises';

// callList 응답의 recordingUrl 필드로 녹음 유무 확인 가능
const list = await client.calls.list({ pageSize: 10 });
for (const call of list.data) {
  if (!call.recordingUrl) continue; // failed/no-answer 등은 null
  const rec = await client.recordings.download(call.callId);
  await writeFile(rec.filename ?? `${call.callId}.wav`, Buffer.from(rec.data));
  console.log(rec.contentType, rec.data.byteLength, 'bytes');
}

녹음이 없는 통화(recordingUrl: null)에 호출하면 NotFoundError(404) 가 발생합니다.

// 녹음 삭제 (멱등 — 이미 없어도 성공)
await client.recordings.delete('CAabcdef1234567890');

전화번호 (Numbers)

// 번호 발급 — 풀에서 자동 배정되며 어떤 번호가 나올지는 지정할 수 없다
const number = await client.numbers.create();
console.log(number.number, number.routingType); // 07012340001 webhook

// 번호 목록 조회 (페이지네이션 없음 — 보유한 번호가 전부 반환된다)
const numbers = await client.numbers.list();

// 발급 직후에는 webhookUrl 이 비어 있어 걸려온 전화가 거절된다. 착신 라우팅을 지정한다.

// 매니지드 에이전트가 받도록
await client.numbers.update('07012340001', {
  routingType: 'agent',
  agentId: 'AG7c2f9b1e4a6d',
});

// 콜 플로우(ARS)가 받도록
await client.numbers.update('07012340001', {
  routingType: 'callflow',
  callFlowId: 'CF41b8e07d9c25',
});

// 내 서버의 VoiceML 이 받도록
await client.numbers.update('07012340001', {
  routingType: 'webhook',
  webhookUrl: 'https://my-app.com/voice',
});

// 보유한 다른 번호로 착신전환 (같은 계정의 번호만 가능)
await client.numbers.update('07012340001', {
  routingType: 'forward',
  forwardTo: '07012340002',
});

// 소프트폰 단말 착신 (sip_trunk 부가서비스 + 등록 단말 필요)
const creds = await client.sipCredentials.list({ status: 'active' });
await client.numbers.update('07012340001', {
  routingType: 'softphone',
  sipCredentialId: creds[0].id,
});

// 외부 PBX 로 (sip_trunk 부가서비스 + 활성 라우트 1개 이상 필요)
const endpoints = await client.sipEndpoints.list({ status: 'active' });
await client.numbers.update('07012340001', { routingType: 'sip', sipEndpointId: endpoints[0].id });

// 수신 통화 상태 통지
await client.numbers.update('07012340001', {
  statusCallback: 'https://my-app.com/call-status',
  statusCallbackEvents: 'initiated ringing answered completed',
});

// 번호 반납 — 되돌릴 수 없고 같은 번호를 다시 받는다는 보장이 없다
await client.numbers.delete('07012340001');

라우팅을 바꾸면 다른 라우팅 필드는 서버에서 자동으로 비워집니다. agent 에서 webhook 으로 되돌리면 agentId 가 null 이 되므로, 다시 agent 로 돌아갈 때 agentId 를 새로 지정해야 합니다.

메시지 (Messages)

// SMS 발송
const msg = await client.messages.create({
  to: '01012345678',
  from: '07052358010',
  body: '안녕하세요',
});
console.log(msg.messageId);

// MMS 발송
const mms = await client.messages.create({
  to: '01012345678',
  from: '07052358010',
  body: '사진 첨부',
  type: 'mms',
  subject: '제목',
});

// LMS (장문 문자) 발송
const lms = await client.messages.create({
  to: '01012345678',
  from: '07052358010',
  body: '긴 내용의 메시지입니다...',
  type: 'lms',
  subject: '알림',
});

// 메시지 목록 조회 (필터링)
const msgPage = await client.messages.list({ type: 'sms', status: 'sent', page: 0, pageSize: 20 });
for (const m of msgPage) {
  console.log(m.messageId, m.status);
}

// 모든 메시지를 자동으로 순회
for await (const m of (await client.messages.list()).autoPagingIter()) {
  console.log(m.messageId);
}

// 특정 메시지 조회
const detail = await client.messages.get('MG0123456789abcdef');

카카오 알림톡 (Kakao)

승인된 템플릿으로 알림톡을 보냅니다. 발송에 필요한 채널·템플릿 ID 는 SDK 로 조회합니다.

// 1. 연결된 카카오 채널
const channels = await client.kakao.channels.list({ status: 'connected' });
const channel = channels.data[0];

// 2. 그 채널의 템플릿 — sendable: true 인 것만 보낼 수 있습니다
const templates = await client.kakao.templates.list({ channelId: channel.id });
const template = templates.data.find((t) => t.sendable);
console.log(template.variables); // ['#{고객명}'] — 이 목록을 모두 채워야 합니다

// 3. 발송
const msg = await client.messages.create({
  to: '01012345678',
  from: '07052358010',
  kakao: {
    channelId: channel.id,
    templateId: template.id,
    variables: { 고객명: '홍길동' }, // '#{고객명}' 표기도 받습니다
  },
  fallback: { body: '주문이 접수되었습니다.' },
});
console.log(msg.type); // 'ata'

본문은 템플릿이 정합니다. 알림톡에는 body·subject·mediaUrl 을 실을 수 없고(컴파일 에러입니다), 버튼·아이템 리스트·강조 문구는 카카오 검수를 받은 그대로 나갑니다 — 발송 요청으로 바꿀 수 없습니다. 요청에서 바꿀 수 있는 것은 variables 값뿐입니다.

대체발송(fallback)은 별도의 메시지 1건으로 기록되고 문자 단가로 청구됩니다. 생략하면 템플릿 본문이 그대로 문자로 나가고, fallback: { disabled: true } 면 알림톡 실패가 그대로 실패로 남습니다.

변수를 빠뜨리면 발송 전에 400 kakao_variable_missing 으로 막힙니다(카카오는 이런 요청도 접수한 뒤 조용히 실패시키므로 ClawOps 가 미리 잡습니다). 사유는 e.code 로 분기하세요.

채널 연결

채널 연결은 두 단계입니다 — 인증번호는 카카오 비즈니스에 등록된 담당자 휴대전화로만 갑니다.

const categories = await client.kakao.channelCategories();

const requested = await client.kakao.channels.requestToken({
  searchId: '@example',
  phoneNumber: '010-1234-5678',
});
console.log(requested.phoneNumberMasked); // '010-****-5678'

// 담당자가 받은 인증번호로 완료 (이미 연결된 채널이면 인증번호를 쓰지 않고 기존 연결을 돌려줍니다)
const channel = await client.kakao.channels.connect({
  searchId: requested.searchId,
  phoneNumber: '010-1234-5678',
  categoryCode: categories.data[0].code,
  token: '394812',
});

⚠️ connect() 가 타임아웃되면 재호출하지 마세요. 이미 연결에 성공했을 수 있습니다 — channels.retrieve(id) 로 실제 등록 여부를 확인하세요(이 조회는 몇 번을 불러도 안전합니다). 연결에 실패해도 인증번호는 소모되므로 원인을 해결한 뒤 requestToken() 부터 다시 시작해야 합니다.

⚠️ channels.disconnect(id) 는 되돌릴 수 없고 그 채널의 알림톡 템플릿까지 함께 삭제합니다. 템플릿은 카카오 검수를 다시 받아야 합니다.

channels.list() 는 저장된 연결 정보를 그대로 돌려줍니다(빠릅니다). 카카오 쪽 상태까지 실제로 확인하는 것은 channels.retrieve() 뿐이며, 이 호출이 status 를 갱신합니다.

카카오 브랜드 메시지 (Brand)

채널을 추가한 친구에게 나가는 광고성 메시지입니다. 등록한 템플릿으로 보냅니다.

const channels = await client.kakao.channels.list({ status: 'connected' });
const templates = await client.kakao.brandTemplates.list({ channelId: channels.data[0].id });

const msg = await client.messages.create({
  to: '01012345678',
  from: '07052358010',
  brand: {
    channelId: channels.data[0].id,
    templateId: templates.data[0].id,
    variables: { 고객명: '홍길동' },
  },
});
console.log(msg.type); // 'bms'

⭐ 알림톡과 달리 검수가 없습니다 — brandTemplates.list() 가 돌려준 템플릿은 전부 바로 쓸 수 있어 sendable 같은 칸이 없습니다. 알림톡 템플릿과는 다른 표라 templates 가 아닌 brandTemplates 로 조회합니다.

알림톡과 갈리는 점 둘:

• 야간에 보낼 수 없습니다. 오후 8시 50분 ~ 다음 날 오전 8시(KST)는 422 kakao_brand_night_blocked 입니다. 접수 전에 막으므로 예약되지 않습니다.
• 대체발송이 없습니다. 카카오톡을 쓰지 않는 수신자에게 문자로 대신 나가지 않습니다. fallback 은 컴파일 에러입니다.

(광고) 표기와 수신거부 안내는 카카오가 자동으로 붙이므로 본문에 넣지 마십시오.

⚠️ 단가가 알림톡보다 훨씬 높고 말풍선 유형에 따라 갈립니다 — 템플릿의 chatBubbleType 이 그 축입니다. content 는 유형에 따라 null 일 수 있습니다(본문이 담기는 자리가 다릅니다).

자유형 — 템플릿 없이 보내기

templateId 대신 free 에 말풍선을 실으면 템플릿을 등록하지 않고 보냅니다. 종료된 친구톡을 대신하는 방식입니다.

const msg = await client.messages.create({
  to: '01012345678',
  from: '07052358010',
  brand: {
    channelId: channels.data[0].id,
    free: {
      chatBubbleType: 'TEXT',
      content: '이번 주 신메뉴가 나왔어요.',
      buttons: [{ name: '메뉴 보기', linkType: 'WL', linkMobile: 'https://example.com' }],
    },
  },
});

templateId 와 free 는 정확히 하나만 실을 수 있습니다 — 둘 다 주거나 둘 다 빼면 컴파일 에러이고, 타입을 쓰지 않는 호출자에게는 400 invalid_input 입니다.

⛔ 자유형에는 변수를 쓸 수 없습니다. 치환해 줄 템플릿이 없어 #{이름} 이 그대로 톡에 렌더되므로 서버가 막습니다. 값을 채우려면 템플릿을 등록해 templateId 로 보내십시오.

⚠️ free 안쪽은 SDK 가 검사하지 않습니다. 말풍선 규격표는 서버에 한 벌만 두는 것이 의도입니다 — SDK 가 사본을 들면 카카오가 칸을 늘린 날 SDK 가 조용히 깎습니다. 잘못된 몸통은 400 으로 돌아오고 무엇이 잘못됐는지 본문이 알려 줍니다.

⚠️ 검수를 거치지 않으므로 여기 실은 버튼 링크가 그대로 톡에 렌더됩니다.

자유형에 이미지 넣기

이미지가 필요한 말풍선 유형은 먼저 올리고 받은 id 를 imageId 에 넣습니다. 한 번 올린 이미지는 여러 발송에 재사용합니다.

const image = await client.kakao.brandImages.upload({
  file: readFileSync('banner.png'),   // Blob 도 됩니다
  filename: 'banner.png',
  bubbleType: 'WIDE',
});

await client.messages.create({
  to: '01012345678',
  from: '07052358010',
  brand: {
    channelId: channels.data[0].id,
    free: { chatBubbleType: 'WIDE', content: '신메뉴가 나왔어요.', imageId: image.id },
  },
});

⚠️ 규격이 말풍선 유형마다 다릅니다. 올릴 때 준 bubbleType 과 다른 유형에 쓰면 카카오가 발송 단계에서 거절합니다 — 그 유형으로 다시 올리십시오. 와이드리스트형의 작은 항목만 slot: 'sub' 를 씁니다(큰 항목은 2:1, 작은 항목은 1:1).

id 를 잃었으면 client.kakao.brandImages.list() 로 되찾습니다.

솔라피(SOLAPI) 호환 — 문자만 ClawOps 로

이미 솔라피 SDK 로 작성된 코드를 그대로 두고 문자(SMS/LMS/MMS)만 ClawOps 로 보냅니다. 알림톡·친구톡·RCS 는 기존 솔라피 계정으로 계속 나갑니다.

npm install @teamlearners/clawops solapi

바꾸는 곳은 인스턴스를 만드는 한 줄뿐입니다.

import { ClawOps } from '@teamlearners/clawops';
import { ClawOpsMessageService } from '@teamlearners/clawops/solapi';
import { SolapiMessageService } from 'solapi';

const messageService = new ClawOpsMessageService({
  clawops: new ClawOps({ apiKey: process.env.CLAWOPS_API_KEY, accountId: process.env.CLAWOPS_ACCOUNT_ID }),
  solapi: new SolapiMessageService(SOLAPI_KEY, SOLAPI_SECRET), // 알림톡을 계속 쓸 때만
  from: '07052358010',                                          // ClawOps 에 등록된 번호
});

// 이 아래 호출부는 기존 코드 그대로입니다
await messageService.send({ to: '01012345678', from: '07052358010', text: '인증번호는 123456 입니다' });

messageService 의 타입은 SolapiMessageService 와 동일해서 기존 코드의 타입 자리에 그대로 들어갑니다. send 만 가로채고 getBalance()·getKakaoChannels() 같은 나머지 메서드는 주입한 솔라피 인스턴스로 그대로 전달합니다. 원본 인스턴스는 수정하지 않습니다.

메시지	어디로
SMS / LMS / MMS	ClawOps
ATA(알림톡) · CTA/CTI(친구톡) · RCS_* · NSA · FAX · VOICE · BMS_*	솔라피 (요청을 손대지 않고 그대로 전달)
type 미지정	kakaoOptions·rcsOptions 같은 vendor 옵션이 있으면 솔라피, 없으면 ClawOps

솔라피는 type 을 필수로 요구하지 않고 vendor 옵션으로 추론합니다. 그래서 우리도 타입 문자열이 아니라 실제로 실린 옵션으로 가릅니다 — send({ to, from, kakaoOptions }) 처럼 type 을 생략한 알림톡도 솔라피로 갑니다.

type 을 SMS/LMS 로 지정하면 그대로 따르고, 지정하지 않고 vendor 옵션도 없으면 서버와 같은 규칙으로 고릅니다 — subject 가 있으면 lms, 본문이 EUC-KR 90 byte(한글 45자) 를 넘으면 lms, 아니면 sms. 솔라피의 SMS 기준과 같습니다(솔라피 상태코드 1029·1031). 기존 분기 로직을 그대로 옮기셔도 됩니다.

⚠️ type: 'SMS' 로 명시한 본문이 90 byte 를 넘으면 ClawOps 는 400 으로 거절합니다. 통신사는 이런 본문을 거절하지 않고 90 byte 에서 잘라서 보내므로, 잘린 문자가 나가는 대신 에러를 돌려줍니다. 길이가 런타임에 정해진다면 type 을 생략하십시오 — 알아서 lms 로 올라갑니다.

imageId 는 솔라피에 업로드된 파일 ID 라 ClawOps 로 옮길 수 없습니다. 이미지가 붙은 메시지는 조용히 텍스트만 보내지 않고 에러를 던집니다. 첨부가 필요하면 client.messages.create 의 mediaUrl 로 직접 발송하십시오. 첨부 없는 MMS 는 위 규칙에 따라 sms/lms 로 나갑니다.

거절은 모두 SolapiBridgeError(ClawOpsError 하위)로 던지므로 SDK 의 다른 에러와 함께 잡을 수 있습니다.

알림톡 실패 시 문자로 대체발송

솔라피의 대체발송은 솔라피에 등록된 발신번호가 있어야 동작합니다. 그 번호가 없으면 알림톡이 실패해도 문자가 나가지 않습니다. 이때 대체발송을 ClawOps 가 대신합니다.

의도는 솔라피 API 의 값 그대로 읽습니다 — 별도 옵션이 필요 없습니다.

보낸 값	동작
from 있음 + disableSms 생략/false	알림톡 실패 시 ClawOps 문자로 대체발송
disableSms: true	대체발송하지 않음
from 없음	대체발송하지 않음 (솔라피 규칙과 동일)

솔라피로 요청을 넘길 때 두 가지를 조정합니다.

• from 을 제외합니다. 솔라피에 등록되지 않은 번호가 실리면 알림톡 자체가 접수 거부됩니다.
• disableSms 를 true 로 보냅니다. 솔라피가 중복으로 문자를 발송하지 않도록.

대체발송 문구는 다음 순서로 정해집니다.

• customFields 에 지정한 문구 (기본 키 clawopsFallbackText) — 문자 전용 문구를 직접 넣을 때
• kakaoOptions.templateId 가 있으면 그 템플릿 본문을 조회해 variables 로 치환 — 알림톡은 보통 text 없이 보내므로 기본 경로입니다. type 을 생략해도 동작합니다
• 그 밖에는 text 가 본문입니다

await messageService.send({
  to: '01012345678',
  from: '07052358010',
  type: 'ATA',
  kakaoOptions: { pfId: 'KA01PF...', templateId: 'TPL_001', variables: { 고객명: '홍길동', 주문번호: 'A-1024' } },
  // 문자로 나갈 때만 다른 문구를 쓰고 싶다면
  customFields: { clawopsFallbackText: '[상점명] 홍길동님 주문 A-1024 가 접수되었습니다.' },
});

치환되지 않은 변수(#{...})가 남으면 발송하지 않고 onBlocked 로 알립니다. #{주문번호} 가 그대로 찍힌 문자가 나가는 것을 막기 위해서입니다.

const messageService = new ClawOpsMessageService({
  clawops, solapi, from: '07052358010',
  fallback: {
    enabled: true,                         // 기본 true. false 면 대체발송하지 않는다
    field: 'clawopsFallbackText',          // customFields 키를 바꾸고 싶을 때
    onFallback: (e) => logger.info({ to: e.to, source: e.source }, '문자로 대체발송'),
    onBlocked:  (e) => logger.warn({ to: e.to, reason: e.reason }, '대체발송 못 함'),
  },
});

대체발송된 건은 솔라피와 같은 의미로 groupInfo.count.sentReplacement 에 집계됩니다.

발송 실패(3XXX)까지 대체발송 — mode: 'sweep'

위까지는 접수 실패만 다룹니다. 그런데 실제로 대체발송이 필요한 건 대부분 접수 이후에 판명됩니다 — 수신자가 카카오톡을 쓰지 않거나(3104) 알림톡을 차단한 경우(3107)는 접수가 성공하고 이통사 리포트에서만 드러납니다.

const messageService = new ClawOpsMessageService({
  clawops, solapi, from: '07052358010',
  fallback: {
    enabled: true,
    mode: 'sweep',                 // 리포트를 주기적으로 훑는다
    intervalMs: 5 * 60_000,        // 기본 5분
    lookbackMs: 60 * 60_000,       // 커서가 없을 때 거슬러 볼 구간. 기본 1시간
    except: RECOMMENDED_EXCLUDED_CODES,  // 기본은 3XXX 전부. 덮으면 안 되는 것만 뺀다
    types: ['ATA'],                // 훑을 타입. 친구톡까지 보려면 ['ATA','CTA','CTI']
    onFallback: (e) => logger.info({ messageId: e.messageId, statusCode: e.statusCode }, '대체발송'),
    onBlocked:  (e) => logger.warn({ messageId: e.messageId, reason: e.reason }, '대체발송 못 함'),
    onError:    (e) => logger.error({ err: e }, '스윕 실패'),  // ← 지정하지 않으면 조용히 넘어갑니다
  },
});

⚠️ onError 를 지정하지 않으면 스윕이 통째로 실패해도 아무 소리가 나지 않습니다. 솔라피 조회가 막히거나 자격증명이 만료되면 다음 주기에 다시 시도할 뿐이고, 그동안 대체발송은 한 건도 나가지 않습니다. 실패가 계속되면 문자가 안 나가는데 로그도 조용한 상태가 되므로, 운영에 올리실 때는 반드시 지정하십시오.

onError 는 스윕 전체가 실패했을 때만 불립니다. 개별 건의 실패는 onBlocked 로 갑니다 (문구를 만들지 못했거나 ClawOps 가 거절한 경우) — 한 건이 실패해도 나머지는 그대로 진행됩니다.

커서를 프로세스 밖에 보관하시려면 initialCursor 로 넣고 onCursor 로 받으십시오. 재시작 후 같은 구간을 다시 훑는 것을 줄여 줍니다(멱등키가 있어 중복 발송은 어차피 막히지만, 요청은 아낍니다).

fallback: {
  enabled: true,
  mode: 'sweep',
  initialCursor: await loadCursor(),   // 없으면 lookbackMs 만큼 거슬러 본다
  onCursor: (cursor) => saveCursor(cursor),  // 직렬화 가능한 값만 담겨 있습니다
}

켜기만 하면 됩니다. 커서·저장소·크론이 필요 없습니다. 발송할 때 customFields 에 마커를 심어 두고, 스윕이 그 마커가 있는 실패 건만 골라 문자를 보냅니다. 고객이 솔라피로 직접 보낸 알림톡은 마커가 없어 건드리지 않습니다.

같은 건을 두 번 보내지 않도록 두 장치가 다르게 동작합니다 — 커서와 처리 집합이 재조회를 막고(정상 운영 중에는 요청이 아예 안 나갑니다), 멱등키가 프로세스 재시작처럼 커서가 비는 순간의 안전망입니다.

알림톡 실패는 3XXX 로만 판정합니다 — 모르는 코드가 오면 실패로 단정하지 않고 다음 스윕에서 다시 봅니다. ClawOps 가 대체 문자를 거절하면 onBlocked 에 reason: 'send_rejected' 로 알리고, 다음 스윕이 다시 시도합니다(멱등키가 같아 중복 발송은 되지 않습니다).

어떤 코드를 대체발송할지

기본은 3XXX 전부입니다. 코드를 골라 담지 않았습니다 — 알림톡이라고 31xx 만 오는 게 아니기 때문입니다. 실측에서 알림톡 건에 3058(전송경로 없음)이 돌아왔습니다. 목록을 추리면 그렇게 새는 코드가 조용히 미발송이 됩니다.

대신 문자로 덮으면 안 되는 코드가 섞여 있습니다. RECOMMENDED_EXCLUDED_CODES 를 except 로 넘겨 빼시는 것을 권합니다.

군	코드	덮으면 생기는 일
수신거부	3061	080 수신거부한 분께 문자가 나갑니다
스팸·발신번호 변작 차단	3054 3055 3059 3112 3113	막힌 발송을 문자로 우회하는 셈이 됩니다
설정 오류	3013 3101 3103 3105 3106 3109 3117	전건이 실패하는데 문자가 덮어, 알림톡이 깨진 걸 오래 모르게 됩니다. 단가도 조용히 올라갑니다
시간 규제	3108	발송 가능 시간이 아닌데 문자로 나갑니다

import { RECOMMENDED_EXCLUDED_CODES } from '@teamlearners/clawops/solapi';

fallback: {
  enabled: true,
  mode: 'sweep',
  except: RECOMMENDED_EXCLUDED_CODES,          // 권장 제외
  // except: [...RECOMMENDED_EXCLUDED_CODES, '3032'],  // 더 빼려면 이어 붙이십시오
}

on 은 반대로 대상을 좁힙니다 — 주시면 그 코드만 나갑니다. on 으로 좁힌 뒤 except 로 다시 뺄 수도 있습니다. on: [] 는 아무것도 보내지 않는다는 뜻이라 기본(전부)과 구별됩니다.

빠진 코드는 조용히 사라지지 않고 onBlocked 에 reason: 'code_not_eligible' 로 알립니다.

상주 프로세스가 없다면(서버리스·크론) 같은 일을 하는 함수를 직접 부르십시오.

import { sweepFailedAlimtalk } from '@teamlearners/clawops/solapi';

const result = await sweepFailedAlimtalk({
  clawops, solapi, from: '07052358010',
  cursor: await loadCursor(),      // 없으면 lookback 만큼 거슬러 본다
});
await saveCursor(result.cursor);   // 직렬화 가능한 값만 담겨 있다

문자 전용 모드

솔라피를 아예 쓰지 않는다면 solapi 를 넘기지 않아도 됩니다. 이때는 타입에서도 send 만 노출되어, 솔라피 전용 메서드를 부르면 컴파일 단계에서 막힙니다.

const messageService = new ClawOpsMessageService({ clawops, from: '07052358010' });
await messageService.send({ to: '01012345678', text: '문자' });

알아두어야 할 것

• 다음 경우에는 요청을 그대로 솔라피에 넘깁니다 — 대체발송 마커를 심지 않고 from·disableSms 도 건드리지 않으므로, 솔라피 자체 대체발송이 그대로 동작합니다: fallback 을 껐을 때, 브랜드메시지(kakaoOptions.bms), 그리고 customFields 가 이미 10개(솔라피 상한)를 다 썼을 때.
• mode: 'sweep' 은 한 인스턴스에서만 켜십시오. 여러 프로세스가 동시에 스윕하면 같은 건을 함께 집어 문자가 두 번 나갈 수 있습니다 — 멱등키는 순차 재시도를 막을 뿐, 완전히 동시에 들어온 두 요청은 통과합니다. 다중 인스턴스라면 크론에서 sweepFailedAlimtalk() 를 한 번만 부르십시오.
• 스윕은 알림톡 리포트가 확정된 뒤에 동작하므로 대체발송에 지연이 있습니다(스윕 주기 + 리포트 확정 시간). 즉시 도달해야 하는 메시지는 처음부터 문자로 보내십시오.
• 예약 발송·중복 제거는 지원하지 않습니다. ClawOps 로 가는 메시지가 있는데 scheduledDate 또는 allowDuplicates: false 가 오면 조용히 무시하지 않고 에러를 던집니다.
• 문자 발송이 개별적으로 실패하면 나머지 건은 그대로 접수되고, 실패 건만 failedMessageList 에 statusCode: 'CLAWOPS' 로 담깁니다. 솔라피 상태 코드가 아닙니다.
• 문자만 보낸 요청의 groupInfo 중 balance·point·price·countForCharge 는 ClawOps 에 대응 개념이 없어 0/빈 값이고, groupId 는 CLAWOPS- 로 시작하는 자체 값이라 getGroupMessages() 로 조회되지 않습니다.
• 알림톡이 포함된 요청은 솔라피가 준 groupInfo 를 이어받되, 접수 집계 (total·registeredSuccess·registeredFailed)는 우리가 보낸 문자까지 합쳐 다시 셉니다. 발송 단계 집계(sentSuccess 등)는 솔라피 값 그대로입니다.
• 전화번호는 하이픈 유무와 무관하게 처리합니다(010-1111-2222 로 보내도 됩니다).
• 광고성 알림톡을 문자로 대체발송하면 광고 문자에 요구되는 표기·수신거부 안내·야간 발송 제한이 적용됩니다. 해당 템플릿은 disableSms: true 로 두거나 customFields 로 문구를 조정하십시오.

멀티 계정 접근

// 다른 계정의 리소스에 접근
const other = client.accounts('AC_other_account_id');
await other.calls.list();
await other.numbers.list();
await other.messages.list();

웹훅 서명 검증

client.webhooks.verify({
  url: 'https://my-app.com/webhook',
  params: { CallId: 'CA...', CallStatus: 'completed' },
  signature: request.headers['x-signature'],
  signingKey: 'your_account_signing_key',
});

서명이 유효하지 않으면 WebhookVerificationError가 발생합니다.

에러 처리

import ClawOps, { BadRequestError, AuthenticationError, NotFoundError } from '@teamlearners/clawops';

const client = new ClawOps();

try {
  const call = await client.calls.create({ to: '01012345678', from: '07052358010', url: 'https://...' });
} catch (e) {
  if (e instanceof BadRequestError) {
    console.log(`잘못된 요청: ${e.status} - ${JSON.stringify(e.body)}`);
  } else if (e instanceof AuthenticationError) {
    console.log(`유효하지 않은 API 키: ${e.status}`);
  } else if (e instanceof NotFoundError) {
    console.log(`리소스를 찾을 수 없음: ${e.status}`);
  }
}

모든 에러는 ClawOpsError를 상속합니다. HTTP 에러는 status, code, body 속성을 제공합니다.

사유는 code 로 분기하세요 — 한 상태 코드가 서로 다른 사유를 담고, 한글 메시지는 바뀔 수 있습니다. 서버가 code 를 싣지 않은 응답에서는 undefined 입니다.

import { UnprocessableEntityError } from '@teamlearners/clawops';

try {
  await client.messages.create({ to, from, kakao: { channelId, templateId, variables } });
} catch (e) {
  if (e instanceof UnprocessableEntityError && e.code === 'recipient_blocked') {
    // 수신거부 — 재시도하면 안 됩니다
  } else if (e instanceof BadRequestError && e.code === 'kakao_variable_missing') {
    // 템플릿 변수 누락 — templates.list() 의 variables 를 다시 확인하세요
  }
}

에러	상태 코드
BadRequestError	400
AuthenticationError	401
PermissionDeniedError	403
NotFoundError	404
ConflictError	409
UnprocessableEntityError	422
InternalServerError	500+
ServiceUnavailableError	503

설정

재시도

기본적으로 408, 409, 429, 500+ 에러 시 지수 백오프로 최대 2회 재시도합니다.

const client = new ClawOps({ maxRetries: 5 });

// 재시도 비활성화
const client = new ClawOps({ maxRetries: 0 });

타임아웃

기본 타임아웃은 600초입니다. 클라이언트 단위로 변경할 수 있습니다:

const client = new ClawOps({ timeout: 30_000 }); // 30초 (밀리초)

커스텀 fetch

프록시 등 고급 설정이 필요한 경우 커스텀 fetch 함수를 주입할 수 있습니다:

import { ProxyAgent } from 'undici';

const dispatcher = new ProxyAgent('http://proxy.example.com:8080');
const client = new ClawOps({
  fetch: (url, init) => fetch(url, { ...init, dispatcher }),
});

환경변수

변수	설명	필수 여부
CLAWOPS_API_KEY	API 키 (sk_...)	예 (생성자에 전달하지 않은 경우)
CLAWOPS_ACCOUNT_ID	기본 계정 ID (AC...)	예 (생성자에 전달하지 않은 경우)
CLAWOPS_BASE_URL	API 기본 URL	아니오 (기본값: https://api.claw-ops.com)
OPENAI_API_KEY	OpenAI API 키	OpenAI Realtime 사용 시
GOOGLE_API_KEY	Google API 키	Gemini Realtime 사용 시

문서

• AI Agent 가이드 — 음성 에이전트 상세 사용법, 파이프라인 모드, 커스텀 제공자, MCP 연동

다른 언어

언어	패키지	저장소
Python	clawops	sdk-python

요구사항

• Node.js 18+
• zod >= 3.23
• ws >= 8.0 (Agent 사용 시)

라이선스

Apache-2.0