bizgo Developers

Best practices

Recommended patterns for running the Bizgo API reliably in production.

1. Always configure failover

If you use only one channel such as Kakao or RCS, a send fails completely when the device does not support it or the channel goes down.
We recommend that you always include SMS as the last failover step.

JSON
"messageFlow": [
  { "kakaoAlimtalk": { ... } },
  { "sms": { "from": "0200000000", "text": "대체 문자" } }
]

2. Always store msgKey

You need the msgKey from the send response later to look up delivery results, raise inquiries, and retry.
If you do not store it in your database, you cannot track the result.

JavaScript
const response = await sendMessage(payload);
const msgKey = response.data.data.destinations[0].msgKey;

// DB에 저장
await db.messages.insert({ msgKey, ref: payload.ref, status: 'sent' });

3. Put the ref field to work

Set ref to an internal identifier such as an order ID or user ID, and you can tie delivery results back to your own systems.

JSON
{
  "destinations": [{ "to": "01000000000" }],
  "messageFlow": [{ "sms": { ... } }],
  "ref": "order-20260403-001"
}

4. Keep your API key in server environment variables only

Bash
# .env
BIZGO_API_KEY=your_api_key_here
JavaScript
// 코드에 직접 하드코딩 금지
const apiKey = process.env.BIZGO_API_KEY; // ✓
const apiKey = "실제키값";                // ✗

If your key is exposed, revoke it in the console and reissue it immediately.

5. Respond to webhooks quickly

Your webhook receiver must return an HTTP 200 within 5 seconds.
Move heavy processing off the request path.

JavaScript
app.post('/webhook/bizgo', async (req, res) => {
  // 즉시 200 응답
  res.status(200).json({ result: 'ok' });

  // 처리는 비동기로
  setImmediate(() => processReport(req.body));
});

6. Guard against duplicate processing

Webhook retries mean you may receive the report for the same msgKey more than once.
Implement idempotent handling keyed on msgKey.

JavaScript
async function processReport(report) {
  const exists = await db.reports.findOne({ msgKey: report.msgKey });
  if (exists) return; // 이미 처리된 경우 무시

  await db.reports.insert(report);
  // 후속 처리...
}

7. Test in the Sandbox environment first

Always test in the Sandbox environment before you send in production.

  • Sandbox base URL: https://sandbox-mars.ibapi.kr/api/comm
  • Sandbox webhook source IP: 211.115.98.231

8. Pre-register your sender numbers

Carriers block sends from unregistered sender numbers.
Register your sender number in the console before you send SMS, LMS, or MMS.

9. Prepare Alimtalk templates ahead of time

Alimtalk template review is processed within 2 business days.
Submit your registration request early so it fits your launch schedule.

10. Mask sensitive data in error logs

Mask sensitive data such as phone numbers and verification codes in your logs.

JavaScript
function maskPhone(phone) {
  return phone.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2');
}

console.log(`발송 대상: ${maskPhone('01012345678')}`); // 010****5678