Amazon SQS と Lambda で Amazon Connect の StartOutboundVoiceContact API 呼び出し回数を抑える構成を試してみた

SQS 標準キュー
↓
Lambda
↓
Amazon Connect StartOutboundVoiceContact

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "StartOutboundVoiceContactInSpecificConnectInstance",
      "Effect": "Allow",
      "Action": "connect:StartOutboundVoiceContact",
      "Resource": "arn:aws:connect:ap-northeast-1:111111111111:instance/<connect-instance-id>/contact/*"
    }
  ]
}

SQS 標準キュー
↓
最大2並列でLambdaを起動
↓
各LambdaはSQSメッセージを1件だけ処理
↓
各LambdaはStartOutboundVoiceContact APIを1回だけ呼び出す
↓
API呼び出し後に1秒sleepして終了

StartOutboundVoiceContact
↓
1秒sleep
↓
Lambda終了

CONNECT_INSTANCE_ID = os.environ["CONNECT_INSTANCE_ID"]
CONTACT_FLOW_ID = os.environ["CONTACT_FLOW_ID"]
SOURCE_PHONE_NUMBER = os.environ["SOURCE_PHONE_NUMBER"]

import json
import os
import time
import hashlib

import boto3

connect = boto3.client("connect")

CONNECT_INSTANCE_ID = os.environ["CONNECT_INSTANCE_ID"]
CONTACT_FLOW_ID = os.environ["CONTACT_FLOW_ID"]
SOURCE_PHONE_NUMBER = os.environ["SOURCE_PHONE_NUMBER"]

# StartOutboundVoiceContact API 呼び出し後に待機する秒数。
# SQS event source mapping:
#   - Maximum concurrency = 2
#   - Batch size = 1
#
# 1回のLambda起動でSQSメッセージを1件処理し、
# API呼び出し後に1秒sleepしてから終了する。
POST_API_SLEEP_SECONDS = 1.0

def lambda_handler(event, context):
    print_json({
        "event": "lambda_invocation_start",
        "aws_request_id": context.aws_request_id,
        "record_count": len(event.get("Records", []))
    })

    for record in event.get("Records", []):
        body = parse_body(record)

        destination_phone_number = body.get("destinationPhoneNumber")
        if not destination_phone_number:
            raise ValueError("destinationPhoneNumber is required in SQS message body")

        client_token = body.get("clientToken") or make_client_token(record)
        message = body.get("message", "")

        api_start_epoch_ms = int(time.time() * 1000)

        print_json({
            "event": "connect_api_start",
            "api_start_epoch_ms": api_start_epoch_ms,
            "aws_request_id": context.aws_request_id,
            "sqs_message_id": record.get("messageId"),
            "client_token": client_token,
            "destination_phone_number": destination_phone_number,
            "message": message
        })

        try:
            response = connect.start_outbound_voice_contact(
                InstanceId=CONNECT_INSTANCE_ID,
                ContactFlowId=CONTACT_FLOW_ID,
                DestinationPhoneNumber=destination_phone_number,
                SourcePhoneNumber=SOURCE_PHONE_NUMBER,
                ClientToken=client_token,
                Attributes={
                    "source": "sqs-rate-limited-call",
                    "message": message[:500],
                    "clientToken": client_token
                }
            )

            print_json({
                "event": "connect_api_success",
                "api_start_epoch_ms": api_start_epoch_ms,
                "api_end_epoch_ms": int(time.time() * 1000),
                "aws_request_id": context.aws_request_id,
                "sqs_message_id": record.get("messageId"),
                "client_token": client_token,
                "contact_id": response.get("ContactId")
            })

        except Exception as e:
            print_json({
                "event": "connect_api_failed",
                "api_start_epoch_ms": api_start_epoch_ms,
                "api_end_epoch_ms": int(time.time() * 1000),
                "aws_request_id": context.aws_request_id,
                "sqs_message_id": record.get("messageId"),
                "client_token": client_token,
                "error": str(e)
            })

            # ここで握りつぶさない。
            # raise することで SQS メッセージは削除されず、
            # Visibility timeout 後に再処理される。
            raise

        finally:
            print_json({
                "event": "post_api_sleep_start",
                "sleep_seconds": POST_API_SLEEP_SECONDS,
                "aws_request_id": context.aws_request_id,
                "sqs_message_id": record.get("messageId")
            })

            time.sleep(POST_API_SLEEP_SECONDS)

            print_json({
                "event": "post_api_sleep_end",
                "aws_request_id": context.aws_request_id,
                "sqs_message_id": record.get("messageId")
            })

    print_json({
        "event": "lambda_invocation_end",
        "aws_request_id": context.aws_request_id
    })

def parse_body(record: dict) -> dict:
    body_text = record.get("body", "{}")

    try:
        body = json.loads(body_text)
        if isinstance(body, dict):
            return body
        return {}
    except json.JSONDecodeError:
        return {}

def make_client_token(record: dict) -> str:
    """
    clientToken が SQS メッセージ本文にない場合の fallback。
    同じSQSメッセージの再処理では同じClientTokenになるようにする。
    """
    message_id = record.get("messageId", "")
    body = record.get("body", "")
    raw = f"{message_id}:{body}"
    return hashlib.sha256(raw.encode("utf-8")).hexdigest()

def print_json(obj: dict):
    print(json.dumps(obj, ensure_ascii=False, separators=(",", ":")))

{
  "destinationPhoneNumber": "+8190xxxxxxxx",
  "clientToken": "manual-call-001",
  "message": "manual call 001"
}

QUEUE_URL=$(aws sqs get-queue-url \
  --queue-name connect-rate-limited-call-queue \
  --query 'QueueUrl' \
  --output text)

RUN_ID=$(date +%Y%m%d%H%M%S)

for i in $(seq 1 10); do
  aws sqs send-message \
    --queue-url "$QUEUE_URL" \
    --message-body "{\"destinationPhoneNumber\":\"+8190xxxxxxxx\",\"clientToken\":\"burst-call-${RUN_ID}-${i}\",\"message\":\"burst call ${i}\"}" \
    >/dev/null &
done

wait
echo "sent 10 messages. run_id=${RUN_ID}"

sent 10 messages. run_id=20260515044151

{
  "event": "connect_api_start",
  "api_start_epoch_ms": 1778820122541,
  "client_token": "burst-call-20260515044151-10"
}

fields @timestamp, event, api_start_epoch_ms, aws_request_id, client_token
| filter client_token like /burst-call-20260515044151/
| filter event = "connect_api_start"
| sort api_start_epoch_ms asc

@timestamp,event,api_start_epoch_ms,aws_request_id,client_token
2026-05-15 04:42:02.541,connect_api_start,1778820122541,c3c8c856-2fb4-58d5-b32b-aad689e42d67,burst-call-20260515044151-10
2026-05-15 04:42:03.452,connect_api_start,1778820123452,b3c75d48-c1f8-588c-a75d-3fc867a0a17c,burst-call-20260515044151-9
2026-05-15 04:42:05.474,connect_api_start,1778820125474,1c921c3f-3edf-5a8e-abd5-7ebf9882ef3c,burst-call-20260515044151-1
2026-05-15 04:42:05.912,connect_api_start,1778820125912,a9f0739e-aa1c-529c-b0aa-111e0c41bb6c,burst-call-20260515044151-4
2026-05-15 04:42:07.802,connect_api_start,1778820127802,32c7bec8-a71e-5012-9ed8-dc480141f5a0,burst-call-20260515044151-3
2026-05-15 04:42:08.157,connect_api_start,1778820128155,a16fbd66-d755-5b82-bf7c-dfe671350272,burst-call-20260515044151-8
2026-05-15 04:42:10.430,connect_api_start,1778820130430,5506334b-716c-5163-abea-51cbd70e74d1,burst-call-20260515044151-6
2026-05-15 04:42:10.655,connect_api_start,1778820130655,106ff95e-20ff-55c6-a45e-9bde869dfc36,burst-call-20260515044151-5
2026-05-15 04:42:12.981,connect_api_start,1778820132981,8f90acc0-997e-5ea1-a565-ce403f1a5b13,burst-call-20260515044151-2
2026-05-15 04:42:13.069,connect_api_start,1778820133069,7bfb9ad0-8671-5c74-ba4c-f85020143584,burst-call-20260515044151-7

3件目の API 呼び出し開始時刻 - 1件目の API 呼び出し開始時刻 < 1000ミリ秒

1778820122541
1778820123452
1778820125474
1778820125912
1778820127802
1778820128155
1778820130430
1778820130655
1778820132981
1778820133069

1件目～3件目：1778820125474 - 1778820122541 = 2933ミリ秒
2件目～4件目：1778820125912 - 1778820123452 = 2460ミリ秒
3件目～5件目：1778820127802 - 1778820125474 = 2328ミリ秒
4件目～6件目：1778820128155 - 1778820125912 = 2243ミリ秒
5件目～7件目：1778820130430 - 1778820127802 = 2628ミリ秒
6件目～8件目：1778820130655 - 1778820128155 = 2500ミリ秒
7件目～9件目：1778820132981 - 1778820130430 = 2551ミリ秒
8件目～10件目：1778820133069 - 1778820130655 = 2414ミリ秒

fields event, client_token, contact_id, error
| filter client_token like /burst-call-20260515044151/
| filter event in ["connect_api_success", "connect_api_failed"]
| stats count(*) as count by event

event,count
connect_api_success,10

burst-call-20260515044151-10
burst-call-20260515044151-9
burst-call-20260515044151-1
burst-call-20260515044151-4
burst-call-20260515044151-3
burst-call-20260515044151-8
burst-call-20260515044151-6
burst-call-20260515044151-5
burst-call-20260515044151-2
burst-call-20260515044151-7