Sample code for 30+ languages & platforms
PureBasic Requires Chilkat v11.0.0+

Clickatell One API: Send an SMS and get its message ID

See more Clickatell Examples

Send one text using an SMS-enabled One API integration. Supply an international phone number starting with the country code, using digits only. For a US two-way integration, set from to its provisioned two-way number. With a test integration, use a registered test phone.

HTTP 202 means the submission was processed. Inspect accepted for each message. Save the returned apiMessageId with the application record and use it to look up delivery status. When a multi-message submission returns HTTP 207, check each result before retrying any rejected message.

Already using the SMS-only REST integration? Its documented request is POST /messages with the integration key in Authorization and a body such as {"content":"Test message","to":["PHONE_NUMBER"]}. One API has a different request body and a separate integration key. SMS API reference

Clickatell API reference

Chilkat PureBasic Downloads

PureBasic
IncludeFile "CkHttpResponse.pb"
IncludeFile "CkHttp.pb"
IncludeFile "CkJsonObject.pb"

Procedure ChilkatExample()

    success.i = 0

    ;  Assumes Chilkat is unlocked. See Global Unlock Sample.
    http.i = CkHttp::ckCreate()
    If http.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    CkHttp::setCkRequireSslCertVerify(http, 1)
    ;  Supply the key for this One API integration from application configuration.
    CkHttp::ckSetRequestHeader(http,"Authorization","ONE_API_KEY")
    CkHttp::ckSetRequestHeader(http,"Accept","application/json")

    body.i = CkJsonObject::ckCreate()
    If body.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    CkJsonObject::ckUpdateString(body,"messages[0].channel","sms")
    CkJsonObject::ckUpdateString(body,"messages[0].to","PHONE_NUMBER")
    CkJsonObject::ckUpdateString(body,"messages[0].content","Test message: your order is ready.")
    ;  For a two-way sender, supply the number provisioned on the integration.
    sender.s = ""
    If sender <> ""
        CkJsonObject::ckUpdateString(body,"messages[0].from",sender)
    EndIf

    resp.i = CkHttpResponse::ckCreate()
    If resp.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    success = CkHttp::ckHttpJson(http,"POST","https://platform.clickatell.com/v1/message",body,"application/json",resp)
    If CkHttpResponse::ckStatusCode(resp) = 0
        Debug "The send outcome is unknown. Check the message report before resending."
        CkHttp::ckDispose(http)
        CkJsonObject::ckDispose(body)
        CkHttpResponse::ckDispose(resp)
        ProcedureReturn
    EndIf

    reply.i = CkJsonObject::ckCreate()
    If reply.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    parsed.i = CkJsonObject::ckLoad(reply,CkHttpResponse::ckBodyStr(resp))
    If (success <> 1) OR ((CkHttpResponse::ckStatusCode(resp) <> 202) AND (CkHttpResponse::ckStatusCode(resp) <> 207))
        Debug "Clickatell returned HTTP " + Str(CkHttpResponse::ckStatusCode(resp))
        If parsed = 1
            If CkJsonObject::ckHasMember(reply,"error.description") = 1
                Debug CkJsonObject::ckStringOf(reply,"error.description")
            EndIf

        EndIf

        CkHttp::ckDispose(http)
        CkJsonObject::ckDispose(body)
        CkHttpResponse::ckDispose(resp)
        CkJsonObject::ckDispose(reply)
        ProcedureReturn
    EndIf

    If parsed <> 1
        Debug "Expected a JSON response."
        CkHttp::ckDispose(http)
        CkJsonObject::ckDispose(body)
        CkHttpResponse::ckDispose(resp)
        CkJsonObject::ckDispose(reply)
        ProcedureReturn
    EndIf

    ;  A request-level error applies to the submission as a whole.
    If CkJsonObject::ckHasMember(reply,"error.code") = 1
        If CkJsonObject::ckIsNullOf(reply,"error.code") <> 1
            Debug "Submission error " + CkJsonObject::ckStringOf(reply,"error.code") + "  " + CkJsonObject::ckStringOf(reply,"error.description")
            CkHttp::ckDispose(http)
            CkJsonObject::ckDispose(body)
            CkHttpResponse::ckDispose(resp)
            CkJsonObject::ckDispose(reply)
            ProcedureReturn
        EndIf

    EndIf

    count.i = CkJsonObject::ckSizeOfArray(reply,"messages")
    If count <= 0
        Debug "No recipient results returned. Check the message report before resending."
        CkHttp::ckDispose(http)
        CkJsonObject::ckDispose(body)
        CkHttpResponse::ckDispose(resp)
        CkJsonObject::ckDispose(reply)
        ProcedureReturn
    EndIf

    i.i = 0
    While (i < count)
        CkJsonObject::setCkI(reply, i)
        resultNumber.i = i + 1
        ;  JsonTypeOf returns 5 for a JSON boolean.
        If CkJsonObject::ckJsonTypeOf(reply,"messages[i].accepted") <> 5
            Debug "Result " + Str(resultNumber) + " has no acceptance flag."
        Else
            If CkJsonObject::ckBoolOf(reply,"messages[i].accepted") = 1
                messageId.s = CkJsonObject::ckStringOf(reply,"messages[i].apiMessageId")
                If (CkJsonObject::ckJsonTypeOf(reply,"messages[i].apiMessageId") <> 1) OR (messageId = "")
                    Debug "Result " + Str(resultNumber) + " was accepted without a tracking ID."
                Else
                    Debug "Result " + Str(resultNumber) + " accepted. Message ID: " + messageId
                EndIf

            Else
                Debug "Result " + Str(resultNumber) + " rejected: " + CkJsonObject::ckStringOf(reply,"messages[i].error.code") + "  " + CkJsonObject::ckStringOf(reply,"messages[i].error.description")
            EndIf

        EndIf

        i = i + 1
    Wend


    CkHttp::ckDispose(http)
    CkJsonObject::ckDispose(body)
    CkHttpResponse::ckDispose(resp)
    CkJsonObject::ckDispose(reply)


    ProcedureReturn
EndProcedure