To send an SMS from a Temporal workflow, put the HTTP call to the messaging API inside an activity, never in workflow code, and build the Idempotency-Key from the workflow ID plus a step name. Temporal will retry the activity on failure, and because every attempt sends the same key, a retry can't text the recipient twice. The workflow stays deterministic, and the activity does the one thing that touches the outside world.
Temporal makes durability easy and duplicates easy at the same time. An activity can run more than once by design, so "at least once" is the contract you're signing. We make Ready, so the examples use the Ready REST API and only the request shape we document. The code is Python with the Temporal SDK, but the structure is the same in Go, Java, TypeScript and .NET.
Why the send belongs in an activity
Workflow code must be deterministic, because Temporal replays it from history to rebuild state. A network call in workflow code would behave differently on replay. Activities are the place for side effects, and they come with timeouts and a retry policy you control.
Activities are retried when:
- The worker crashes or is deployed mid-call.
- The activity times out, including after the API has already queued the text.
- The activity raises an error that your policy treats as retryable.
In each case Temporal can't know whether the HTTP request reached the API. That's the same uncertainty as any client timeout, and the same answer applies: send a key that stays constant for the logical message.
Derive the key from the workflow, not the attempt
Temporal gives you stable identifiers. The workflow ID is unique per execution and stays the same through retries, replays and continue-as-new chains of the same logical job. Each activity attempt has an attempt number, which changes. Use the first and ignore the second.
A good key is <workflow_id>:<step>, for example welcome-flow-8841:day-0-text. If one workflow sends several texts, the step name keeps them apart. Keep to stable business IDs in the workflow ID, such as a customer ID, instead of phone numbers.
| Key ingredient | Stable across activity retries? | Use it? |
|---|---|---|
| Workflow ID | Yes | Yes |
| Step name in the workflow | Yes | Yes |
| Activity attempt number | No | No |
| Random UUID generated inside the activity | No | No |
| Random UUID generated in the workflow via the SDK's deterministic helper | Yes, replay-safe | Fine, but the workflow ID is simpler |
A random UUID created inside the activity is the common mistake. It looks like what the API docs recommend, but each attempt gets a new one, so retries become new messages.
The activity and the workflow
Here's the activity. It reads the key from its input, so the workflow owns the identity:
import os
from dataclasses import dataclass
from datetime import timedelta
import httpx
from temporalio import activity, workflow
from temporalio.common import RetryPolicy
from temporalio.exceptions import ApplicationError
API = "https://api.tryready.com/v1/messages"
@dataclass
class SmsInput:
to: str
body: str
idempotency_key: str
@activity.defn
async def send_sms(inp: SmsInput) -> str:
async with httpx.AsyncClient(timeout=15) as client:
res = await client.post(
API,
headers={
"X-API-Key": os.environ["READY_API_KEY"],
"Idempotency-Key": inp.idempotency_key,
},
json={"to": inp.to, "body": inp.body, "consent_attested": True},
)
if res.status_code == 429 or res.status_code >= 500:
res.raise_for_status() # retryable: Temporal retries with the same key
if res.status_code >= 400:
raise ApplicationError(
f"refused: {res.status_code} {res.text[:200]}",
non_retryable=True,
)
return res.text
@workflow.defn
class WelcomeFlow:
@workflow.run
async def run(self, customer_id: str, phone: str) -> None:
wf_id = workflow.info().workflow_id
await workflow.execute_activity(
send_sms,
SmsInput(phone, "Welcome aboard. Your account is ready.", f"{wf_id}:day-0-text"),
start_to_close_timeout=timedelta(seconds=30),
retry_policy=RetryPolicy(
initial_interval=timedelta(seconds=2),
backoff_coefficient=2.0,
maximum_interval=timedelta(minutes=2),
maximum_attempts=5,
),
)
await workflow.sleep(timedelta(days=2))
await workflow.execute_activity(
send_sms,
SmsInput(phone, "Need a hand getting set up? Just reply here.", f"{wf_id}:day-2-text"),
start_to_close_timeout=timedelta(seconds=30),
retry_policy=RetryPolicy(maximum_attempts=5),
) Three things matter here. The key goes in as data, so every attempt of that activity sees the same string. A 429 or a server error raises and gets retried, while any other 4xx raises a non-retryable ApplicationError, since a malformed number won't improve on attempt five. And workflow.sleep waits two days durably, so the second text happens even if every worker restarts in between.
Choosing retry and timeout settings
Set a start_to_close_timeout a little above the HTTP timeout, so the activity fails cleanly instead of hanging. Cap maximum_attempts rather than retrying forever: an outage of an hour shouldn't produce a queue of thousands of retrying texts when it ends. If a text is time-sensitive, such as a one-time code, a short schedule_to_close_timeout stops a very late send.
Retries with the same key are safe for timeouts and 429. For a 5xx or an unclear outcome, read the error codes page and check GET /v1/messages before resending under a new key. Our posts on retries and failure handling and idempotency and duplicate texts cover each status.
Opt-outs and quiet hours in a long-running workflow
A workflow that sleeps for days is exactly where consent changes. Someone can reply STOP on day one. Ready refuses opted-out numbers and numbers on your Ban list up front, without a charge, so the day-two text is refused rather than sent. Treat that refusal as final and end the workflow cleanly. For a list that came from another tool, check GET /v1/opt-outs/:phone first. The opt-out API post shows how to read the opt-out list.
Quiet hours work the same way. An API text is held only if the recipient's window opens within 6 hours. Otherwise the API answers 409 QUIET_HOURS_BLOCK and sends nothing. Make that a non-retryable result, then have the workflow sleep until the window opens and send again with a new step name, or send with hold_until_allowed: true to hold it up to 24 hours.
What the key doesn't cover
If your workflow ID is reused for a different logical job, the key is reused too, and the API may treat the new text as the old one. Keep workflow IDs unique per business event. If two workflows start for the same customer, they have different IDs and send two texts, so use your workflow ID conflict policy to prevent that at start time.
A worked cost example
Assume a welcome flow sends two one-segment texts to each of 1,000 new customers, no emoji. That's 2,000 segments, so 2,000 × ($0.0075 + $0.0045), at the Standard rate plus the carrier fee. Screening is extra when you switch it on. A card on file and a number of your own are required to send, and accounts opened before November 12, 2026 keep their signup prices, shown under Billing.
Ready's all-in prices per segment include the carrier fee but not screening: Scrub lists and Number validation, the two switches in Settings under Compliance, each add $0.003 per segment when switched on, shown as screening on your bill, and both are off by default. Unless you turn the opt-out footer off, the first text to each contact, and one again from time to time, also gets "Reply STOP to opt out" and your business name if the message does not already have them, so a text close to the segment limit can bill one more segment.
Frequently asked questions
Can I call the API directly from workflow code?
No. Workflow code is replayed, so a network call there breaks determinism. Wrap it in an activity.
Does Temporal exactly-once execution remove the need for an idempotency key?
No. Temporal guarantees workflow progress, and activities run at least once. The key is what makes the text itself safe to repeat.
How do I receive replies in a workflow?
Run a webhook handler that signals the workflow by ID. Our guide to receiving inbound webhooks covers the receiving side.
Where to go next
The takeaway: one activity for the send, one key per step built from the workflow ID, a retry policy with a cap, and non-retryable errors for refusals. When you're ready to try it, the API quickstart covers the key and a first send.