Numbers

Order a number, read its SMS, close it — client.Numbers().

An operation (tzid) is one ordered number. Order it with Get/GetWithNumber, read the SMS with StateOne or WaitCode, finish it with Close (or Ban). Countries are phone codes (7, 44, …), services are slugs (google, vkcom, …) as returned by Tariffs.

Price

Price of one number, USD; nil when the country has no price for the service.

func (n *NumbersAPI) Price(ctx context.Context, service string, country int) (*float64, error)
ParamTypeDescription
servicestringService slug.
countryintCountry code.
usd, err := client.Numbers().Price(ctx, "google", 44)
if err == nil && usd != nil {
    fmt.Println(*usd)
}

Errors: *APIError ERROR_NO_SERVICE, UNDEFINED_COUNTRY.

Get

Order a number; returns the operation id. Freezes the price on the balance.

func (n *NumbersAPI) Get(ctx context.Context, service string, country int, reject ...string) (int64, error)
ParamTypeDescription
servicestringService slug.
countryintCountry code.
reject...stringNumber prefixes to skip, e.g. "4470". None: the profile's list.
tzid, err := client.Numbers().Get(ctx, "google", 44, "4470")
fmt.Println(tzid, err)

Errors: *NoNumberError; *APIError WARNING_LOW_BALANCE, ERROR_NO_SERVICE, UNDEFINED_COUNTRY, EXCEEDED_CONCURRENT_OPERATIONS, INTERVAL_CONCURRENT_REQUESTS_ERROR, TRY_AGAIN_LATER.

GetWithNumber

Same as Get, but returns the number right away.

func (n *NumbersAPI) GetWithNumber(ctx context.Context, service string, country int, reject ...string) (NumberOrder, error)

Returns NumberOrder: {Tzid, Number, Country, Time, Service, Title, GuardIntervalRemainingSeconds} — Number with +, Time in seconds left.

order, err := client.Numbers().GetWithNumber(ctx, "google", 44)
fmt.Println(order.Tzid, order.Number, err)

Errors: as Get.

State

All operations of the account; an empty slice when there are none.

func (n *NumbersAPI) State(ctx context.Context, opts StateOptions) ([]Operation, error)
StateOptions fieldTypeZero valueDescription
FullMessageboolfalseMsg.Text is the full SMS text instead of the code.
OrderByOrderOrderAscOrderAsc or OrderDesc.
MsgListboolfalseMsg.List holds every SMS ([]OperationSMS).

Operation: {Tzid, Response, Number, Service, Country, Sum, Time, Form, Msg, GuardIntervalRemainingSeconds, …}. Response is the state: TZInPool (number being assigned), TZNumWait (waiting for SMS), TZNumAnswer (SMS arrived), TZOverOK (finished), TZErrorNoItems (failed). Msg is empty until the first SMS. The server caches answers for a few seconds.

ops, err := client.Numbers().State(ctx, onlinesim.StateOptions{OrderBy: onlinesim.OrderDesc})
if err != nil {
    return err
}
for _, op := range ops {
    fmt.Println(op.Tzid, op.Response, op.Msg.Text)
}

StateOne

One operation. OrderBy is ignored.

func (n *NumbersAPI) StateOne(ctx context.Context, tzid int64, opts StateOptions) (Operation, error)
op, err := client.Numbers().StateOne(ctx, tzid, onlinesim.StateOptions{})
if err == nil && op.Response == onlinesim.TZNumAnswer {
    fmt.Println(op.Msg.Text)
}

Errors: *APIError ERROR_NO_OPERATIONS when the operation does not exist (any more).

WaitCode

Poll the operation until a code arrives, then close it and return the code.

func (n *NumbersAPI) WaitCode(ctx context.Context, tzid int64, opts WaitCodeOptions) (string, error)
WaitCodeOptions fieldTypeZero valueDescription
Intervaltime.Duration5 sPoll interval.
Timeouttime.Duration600 sGive up after this long.
KeepOpenboolfalseCall Next(tzid) instead of Close(tzid), to wait for another SMS.
FullMessageboolfalseReturn the full SMS text instead of the code.
Sincestring""Ignore this value (the previous code).
Sleepfunc(ctx, d) errorreal timerInjectable for tests.
Nowfunc() time.Timetime.NowInjectable for tests.

Transient errors are retried until the timeout: *TransportError, and *APIError TRY_AGAIN_LATER (the HTTP 429 rate limit), ERROR_UNDEFINED and INTERVAL_CONCURRENT_REQUESTS_ERROR. Any other *APIError is returned at once, and so is the context's error.

n := client.Numbers()
first, err := n.WaitCode(ctx, tzid, onlinesim.WaitCodeOptions{KeepOpen: true})
if err != nil {
    return err
}
second, err := n.WaitCode(ctx, tzid, onlinesim.WaitCodeOptions{Since: first})
fmt.Println(first, second, err)

Errors: ErrTimeout (wrapped); *APIError with code TZ_OVER_OK or ERROR_NO_ITEMS when the operation ended without a new code; any other *APIError from StateOne/Close/Next.

Next

Switch the operation to its next SMS and keep it open (for services that send several SMS).

func (n *NumbersAPI) Next(ctx context.Context, tzid int64) error
err := client.Numbers().Next(ctx, tzid)
fmt.Println(err)

Errors: *APIError ERROR_WRONG_TZID (not an operation of your account), ERROR_NO_TZID.

Close

Finish the operation. An operation without SMS can be closed only after its guard interval (GuardIntervalRemainingSeconds); every attempt locks the tzid for 5 s. The client does not retry.

func (n *NumbersAPI) Close(ctx context.Context, tzid int64) error
err := client.Numbers().Close(ctx, tzid)
fmt.Println(err)

Errors: *APIError NO_COMPLETE_TZID, INTERVAL_CONCURRENT_REQUESTS_ERROR, ERROR_WRONG_TZID.

Ban

Finish the operation and report the number as bad. Only before any SMS arrived.

func (n *NumbersAPI) Ban(ctx context.Context, tzid int64) error
err := client.Numbers().Ban(ctx, tzid)
fmt.Println(err)

Errors: as Close; *APIError with code "0" when the operation already has an SMS — nothing is changed then.

Tariffs

Services, prices and stock of every country, keyed by country code. No API key needed. The answer is large (a few MB); prefer TariffsOne.

func (n *NumbersAPI) Tariffs(ctx context.Context) (map[string]CountryStat, error)

CountryStat: {Name, LocaleName, Position, Code, Other, New, Enabled, Services}; Services maps service_<slug> to ServiceStat{Count, Popular, Code, Price, ID, Service, Slug} (Count is -1 when the server reports "?").

all, err := client.Numbers().Tariffs(ctx)
fmt.Println(len(all), "countries", err)

TariffsOne

Services, prices and stock of one country.

func (n *NumbersAPI) TariffsOne(ctx context.Context, country int) (CountryStat, error)
uk, err := client.Numbers().TariffsOne(ctx, 44)
if err != nil {
    return err
}
for _, s := range uk.Services {
    fmt.Println(s.Slug, s.Price, s.Count)
}

Errors: *APIError NO_COUNTRY.