Hosted SIM API

How a dongle line behaves

Your line is one real SIM in one dongle. That shapes a few things your app should expect.

  1. One call at a time. A second call on the line, through the API or its SIP login, is refused at once with 700001. Calls are never queued.
  2. Rejecting or declining a call gives the caller whatever the SIM's carrier does with a rejected call: usually voicemail; with voicemail off, the network's busy or unavailable message.
  3. No answering-machine detection: a call answered by voicemail reads in-progress.
  4. Incoming calls: the webhook fires about 1-3 seconds after the first ring, and your server must answer within 8 seconds, or the call rings on into the SIM's voicemail. The fallback URL runs only after a fast failure.
  5. Dial><Sip> works for incoming calls only, as the first verb, and DialCallStatus is never busy.
  6. From is always your line's own number.
  7. The first ~1.4 seconds after the answer have no audio. A Media Stream's start waits for it.
  8. Texts report sent as their last status until delivery reports ship. Incoming texts can arrive late but are never lost if our side or yours is down: they wait on the SIM.
  9. No text-to-speech, speech recognition, recording, conferences or MMS out in v1 (planned for v2).
  10. Prices are null: billing is in the console.
  11. Parameters v1 doesn't support are refused, with a code naming them, never ignored.

When a line can't call or text

Your number's dongle.why_not says why, and why_not_text says it in these words. A refused call's 700002 carries the same why_not. It's null while the line serves and can call.

why_not why_not_text
no_calling_dongle This line has no calling dongle: texts only
dongle_offline The line's dongle isn't connected right now
line_suspended The line isn't active: not rented, moving, or ended
temporarily_unavailable The line is briefly unavailable: try again shortly