Testing - Twizo

Testing

Introduction

We offer an easy way to test your integration of our API into your system. Free of charge.

To use our sandbox environment you have to use a test application. Go to the applications list in our portal and get the API key of a test application. If you do not have a test application yet, you can easily create one. Click on ‘Add application’, enter a name you want to call the application, select the ‘Test application’ checkbox and press the Create button. When the application is created, open it and there you see the API key of the test application and you can start sending test messages.

How it works:
Each Twizo API call you do with the test API key is validated as normal, so when you send incorrect parameters the call will be rejected (see Errors for more details on the possible errors). When the call is valid, the Twizo API checks the last 5 digits of the phone number you set. Based on those last digits the testing environment will influence the behaviour of the message. How it behaves depends on the type of message you want to send and the last 5 digits you set.

Notes:
  • You will not be charged for these test calls and they will not be sent to the phone.
  • Regardless of the currency of your wallet, the sandbox will always return the currency code ‘usd’.
  • You will not see the messages in the statistics or be able to find them in the message details.

If you are missing an option to cover a test case, please contact us and we will add that option.

Verification

With the testing environment you can fully test your verification flow. By filling in the phone number you can control the test verification. In the table below you can find an overview of the possible last 5 digits of the phone number. Anything not described in the table will have undefined behaviour but can be used in the future to cover other test scenarios.

Last 5 digits number Status code Status text Reason code
00XXX 0 no status
01XXX 1 success
02XXX 2 rejected Last 3 digits number (Reason codes)
03XXX 3 expired
04XXX 4 failed

In all these cases the verification is accepted by the API, so you will get a HTTP status code in the range of 2xx. After the call is accepted the verification will have the status as defined in the table.

When you request a test verification, a token will be generated as well. The generated token will have a defined value based on the token type (default value: numeric) and length (default value: 6) you set as you can see in this table:

Token length Numeric Alphanumeric
4 0123 A123
5 01234 A1234
6 012345 A12345
7 0123456 A123456
8 01234567 A1234567
9 012345678 A12345678
10 0123456789 A123456789

Example 1 – Test normal verification flow

To test the normal verification flow, submit a verification with a recipient number ending with ’00xxx’. If you do not specify the tokenType and tokenLength, the token of this verification will be ‘012345’. So if you want to test the response when the token is valid enter the token 012345 or if you want to test the response for an invalid token enter any token other then ‘012345’. If you want to test the response for an expired token wait till the validity is expired, by default 60 seconds, and then verify the token or use a phone number ending with ’03xxx’.

To submit the verification:

curl -X POST https://api-asia-01.twizo.com/v1/verification/submit \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "twizo:<API_KEY>" \
    -d '{
        "recipient" : "61123400000"
    }'
curl -X POST https://api-eu-01.twizo.com/v1/verification/submit \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "twizo:<API_KEY>" \
    -d '{
        "recipient" : "61123400000"
    }'

To verify the verification with the correct token:

curl https://api-asia-01.twizo.com/v1/verification/submit/<MESSAGE_ID>?token=012345 \
    -u "twizo:<API_KEY>"
curl https://api-eu-01.twizo.com/v1/verification/submit/<MESSAGE_ID>?token=012345 \
    -u "twizo:<API_KEY>"

Example 2 – Test verify a successful token again

In this case the verification your submitted verification will directly go the status ‘success’. So when you perform a verifyToken on it, you will a HTTP status ‘423 – Locked’ with errorCode 101.

To submit the verification:

curl -X POST https://api-asia-01.twizo.com/v1/verification/submit \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "twizo:<API_KEY>" \
    -d '{
        "recipient" : "61123401000"
    }'
curl -X POST https://api-eu-01.twizo.com/v1/verification/submit \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "twizo:<API_KEY>" \
    -d '{
        "recipient" : "61123401000"
    }'

To verify the token with the correct token:

curl https://api-asia-01.twizo.com/v1/verification/submit/<MESSAGE_ID>?token=012345 \
    -u "twizo:<API_KEY>"
curl https://api-eu-01.twizo.com/v1/verification/submit/<MESSAGE_ID>?token=012345 \
    -u "twizo:<API_KEY>"
Will result in:
{
    "errorCode": 101,
    "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
    "title": "Locked",
    "status": 423,
    "detail": "You are only allowed to check a certain token once."
}

Example 3 – Test verify an expired verification

In this example we submit a verification where the verification will directly be set to expired. When you verify the token you will get the response that it is expired. Submit a verification with a recipient number ending with ’03xxx’. When you verify the token you will get the HTTP status code ‘423 – Locked’ with errorCode 102.

Submit the verification:

curl -X POST https://api-asia-01.twizo.com/v1/verification/submit \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "twizo:<API_KEY>" \
    -d '{
        "recipient" : "61123403000"
    }'
curl -X POST https://api-eu-01.twizo.com/v1/verification/submit \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "twizo:<API_KEY>" \
    -d '{
        "recipient" : "61123403000"
    }'
Verify the token:
curl https://api-asia-01.twizo.com/v1/verification/submit/<MESSAGE_ID>?token=012345 \
    -u "twizo:<API_KEY>"
curl https://api-eu-01.twizo.com/v1/verification/submit/<MESSAGE_ID>?token=012345 \
    -u "twizo:<API_KEY>"
Will result in:
{
    "errorCode": 102,
    "type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
    "title": "Locked",
    "status": 423,
    "detail": "Verification expired, validity expired on: 2017-02-10T14:58:43+00:00"
}

Verification widget

With the testing environment you can fully test your verification widget flow. By filling in the phone number you can control the test verification for sms and call. When you set a recipient ending with ‘00000’, you can use the token ‘012345’ as a valid token. When you set another recipient, the token will be a random number (and therefor hard to enter the correct token ;-)).

For testing backup codes in the widget, you first need to create backup codes using a test API key, see Testing backup codes for more details.

Backup codes

With the testing environment you can easily test your backup code flow. When you create backup codes for the identifier you have set, a predefined set of backup codes will be returned. These backup codes can be used to test, however in test modes they are only available for 7 days. After that the backup codes are removed.

The predefined test backup codes are:

[
    "00000000",
    "11111111",
    "22222222",
    "33333333",
    "44444444",
    "55555555",
    "66666666",
    "77777777",
    "88888888",
    "99999999"
]

SMS

With the testing environment you can fully test your SMS flow. By filling in the phone number you can control the test SMS, including delivery reports. In the table below you can find an overview of the possible last 5 digits of the phone number. Anything not described in the table will have undefined behaviour but can be used in the future to cover other test scenarios.

Last 5 digits number Status code Status text Reason code
00XXX 0 no status
01XXX 1 delivered
02XXX 2 rejected Last 3 digits number (Reason codes)
03XXX 3 expired Last 3 digits number (Reason codes)
04XXX 4 enroute
05XXX 5 buffered
06XXX 6 accepted
07XXX 7 undelivered Last 3 digits number (Reason codes)
08XXX 8 deleted Last 3 digits number (Reason codes)
09XXX 9 unknown Last 3 digits number (Reason codes)

In all these cases the SMS is accepted by the API, so you will get a HTTP status code in the range of 2xx. After the call is accepted the SMS will have the status as defined in the table.

Example – Test SMS when out of credit

In this example we submit an SMS where it will be rejected due to insufficient credit (reason code 201). Submit an SMS with a recipient number ending with ‘03201’.

To submit the SMS:
curl -X POST https://api-asia-01.twizo.com/v1/sms/submitsimple \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "twizo:<API_KEY>" \
    -d '{
        "recipient" : ["61123403201"],
        "body" : "This is a rejected message",
        "sender" : "Twizo"
    }'
curl -X POST https://api-eu-01.twizo.com/v1/sms/submitsimple \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "twizo:<API_KEY>" \
    -d '{
        "recipient" : ["61123403201"],
        "body" : "This is a rejected message",
        "sender" : "Twizo"
    }'
To retrieve the message status after the submit:
curl https://api-asia-01.twizo.com/v1/sms/submitsimple/<MESSAGE_ID> \
    -u "twizo:<API_KEY>"
curl https://api-eu-01.twizo.com/v1/sms/submitsimple/<MESSAGE_ID> \
    -u "twizo:<API_KEY>"
Will result in:
{
    "applicationTag": "Test",
    "body": "This is a rejected message",
    "callbackUrl": null,
    "createdDateTime": "2017-03-02T13:26:07+00:00",
    "dcs": 0,
    "messageId": "asia-01-1.6323.sms58b81d6f43fd08.15384596",
    "networkCode": 12345,
    "pid": null,
    "reasonCode": 201,
    "recipient": "61123403201",
    "resultTimestamp": "2017-03-02T13:26:07+00:00",
    "resultType": 0,
    "salesPrice": 0,
    "salesPriceCurrencyCode": "usd",
    "scheduledDelivery": null,
    "sender": "Twizo",
    "senderNpi": 0,
    "senderTon": 5,
    "status": "expired",
    "statusCode": 3,
    "tag": null,
    "udh": null,
    "validity": 259200,
    "validUntilDateTime": "2017-03-05T13:26:07+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-asia-01.twizo.com\/v1\/sms\/submitsimple\/asia-01-1.6323.sms58b81d6f43fd08.15384596"
        }
    }
}
{
    "applicationTag": "Test",
    "body": "This is a rejected message",
    "callbackUrl": null,
    "createdDateTime": "2017-03-02T13:26:07+00:00",
    "dcs": 0,
    "messageId": "eu-01-1.6323.sms58b81d6f43fd08.15384596",
    "networkCode": 12345,
    "pid": null,
    "reasonCode": 201,
    "recipient": "61123403201",
    "resultTimestamp": "2017-03-02T13:26:07+00:00",
    "resultType": 0,
    "salesPrice": 0,
    "salesPriceCurrencyCode": "usd",
    "scheduledDelivery": null,
    "sender": "Twizo",
    "senderNpi": 0,
    "senderTon": 5,
    "status": "expired",
    "statusCode": 3,
    "tag": null,
    "udh": null,
    "validity": 259200,
    "validUntilDateTime": "2017-03-05T13:26:07+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.twizo.com\/v1\/sms\/submitsimple\/eu-01-1.6323.sms58b81d6f43fd08.15384596"
        }
    }
}

Number Lookup

With the testing environment you can fully test your Number Lookup flow. By filling in the phone number you can control the test Number Lookup, including delivery reports. In the table below you can find an overview of the possible last 5 digits of the phone number. Anything not described in the table will have undefined behaviour but can be used in the future to cover other test scenarios.

Last 5 digits number Status code Status text Reason code
00XXX 0 no status
01XXX 1 delivered
02XXX 2 rejected Last 3 digits number (Reason codes)
03XXX 3 expired Last 3 digits number (Reason codes)
04XXX 4 enroute
05XXX 5 buffered
06XXX 6 accepted
07XXX 7 undelivered Last 3 digits number (Reason codes)
08XXX 8 deleted Last 3 digits number (Reason codes)
09XXX 9 unknown Last 3 digits number (Reason codes)

In all these cases the Number Lookup is accepted by the API, so you will get a HTTP status code in the range of 2xx. After the call is accepted the Number Lookup will have the status as defined in the table.

Example – Test Number Lookup with valid result

In this example we will submit a Number Lookup which will be performed successful and data is returned. Submit an SMS with a recipient number ending with ’01xxx’.

To submit the Number Lookup:
curl -X POST https://api-asia-01.twizo.com/v1/numberlookup/submit \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "twizo:<API_KEY>" \
    -d '{
        "numbers" : ["61123401000"]
    }'
curl -X POST https://api-eu-01.twizo.com/v1/numberlookup/submit \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "twizo:<API_KEY>" \
    -d '{
        "numbers" : ["61123401000"]
    }'
To get the status of the Number Lookup:
curl https://api-asia-01.twizo.com/v1/numberlookup/submit/<MESSAGE_ID> \
    -u "twizo:<API_KEY>"
curl https://api-eu-01.twizo.com/v1/numberlookup/submit/<MESSAGE_ID> \
    -u "twizo:<API_KEY>"
Will result in:
{
    "_links": {
        "self": {
            "href": "https:\/\/api-asia-01.twizo.com\/v1\/numberlookup\/submit"
        }
    },
    "_embedded": {
        "items": [
            {
                "applicationTag": "Test",
                "callbackUrl": null,
                "countryCode": null,
                "createdDateTime": "2017-03-02T13:34:49+00:00",
                "imsi": null,
                "isPorted": "Unknown",
                "isRoaming": "Unknown",
                "messageId": "asia-01-1.6325.nrl58b81f79d3c749.10703469",
                "msc": null,
                "networkCode": null,
                "number": "61123401000",
                "operator": null,
                "reasonCode": null,
                "resultTimestamp": null,
                "resultType": 0,
                "salesPrice": null,
                "salesPriceCurrencyCode": null,
                "status": "no status",
                "statusCode": 0,
                "tag": null,
                "validity": 259200,
                "validUntilDateTime": "2017-03-05T13:34:49+00:00",
                "_links": {
                    "self": {
                        "href": "https:\/\/api-asia-01.twizo.com\/v1\/numberlookup\/submit\/asia-01-1.6325.nrl58b81f79d3c749.10703469"
                    }
                }
            }
        ]
    },
    "total_items": 1
}
{
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.twizo.com\/v1\/numberlookup\/submit"
        }
    },
    "_embedded": {
        "items": [
            {
                "applicationTag": "Test",
                "callbackUrl": null,
                "countryCode": null,
                "createdDateTime": "2017-03-02T13:34:49+00:00",
                "imsi": null,
                "isPorted": "Unknown",
                "isRoaming": "Unknown",
                "messageId": "eu-01-1.6325.nrl58b81f79d3c749.10703469",
                "msc": null,
                "networkCode": null,
                "number": "61123401000",
                "operator": null,
                "reasonCode": null,
                "resultTimestamp": null,
                "resultType": 0,
                "salesPrice": null,
                "salesPriceCurrencyCode": null,
                "status": "no status",
                "statusCode": 0,
                "tag": null,
                "validity": 259200,
                "validUntilDateTime": "2017-03-05T13:34:49+00:00",
                "_links": {
                    "self": {
                        "href": "https:\/\/api-eu-01.twizo.com\/v1\/numberlookup\/submit\/eu-01-1.6325.nrl58b81f79d3c749.10703469"
                    }
                }
            }
        ]
    },
    "total_items": 1
}
Sign up and Get Started for Free

sign up for free
Monthly 100 free verification credits
and no credit card required at sign up!