Skip to content
This repository was archived by the owner on Sep 30, 2022. It is now read-only.

GettingStarted.adoc

Latest commit

 

History

History
124 lines (94 loc) · 5.57 KB

GettingStarted.adoc

File metadata and controls

124 lines (94 loc) · 5.57 KB

Getting started

Installation

To install EzTexting API client, run the following command in the Package Manager Console

PM> Install-Package EzTextingApiClient

or using nuget console tool:

$ nuget install EzTextingApiClient

it will install the latest public version, other releases you can find at releases page. After these steps EzTextingApiClient should appear in your project dependencies along with other transitive ones.

  • Note for Visual Studio installation: to be able to use api client please manually copy EzTextingApiClient.dll.config from your solutionFolder\packages\EzTextingApiClient.?.?.? folder to target dir. You can use post-build event for that (https://msdn.microsoft.com/en-us/library/ke5z92ks.aspx). Command example for post-build event:

    xcopy "$(SolutionDir)packages\EzTextingApiClient.?.?.?\lib\EzTextingApiClient.dll.config" "$(TargetDir)" /i /R /Y

In case you want to build it yourself:

    $ git clone https://github.com/CallFire/eztexting-api-client-csharp.git
    $ cd eztexting-api-client-csharp
    // build on windows platform
    $ gradlew.bat clean nugetPack
    // build on unix platforms
    $ ./gradlew clean nugetPack

it will produce zip & Nuget packages in build/pkg directory:

    EzTextingApiClient.dll - client assembly
    EzTextingApiClient.dll.config - configuration file
    EzTextingApiClient.xml - XML documentation

then you can install Nuget package locally or unpack zip package into your project’s lib directory.

Overview

To create client instance just provide your account’s login and password. Client uses HTTPS connection. By default it connects to EzTexting site, but you can specify any other related brand: ClubTexting, GroupTexting, TellMyCell, etc.

Example how to get your account’s credit balance:

    class MainClass
    {
        public static void Main(string[] args)
        {
            EzTextingClient client = new EzTextingClient("user", "pass");
            Console.WriteLine("account balance: " + client.CreditsApi.CheckBalance());
        }
    }
List of API groups:
    EzTextingClient client = new EzTextingClient("login", "password");
    client.ContactsApi; - add/get/update/delete contacts
    client.CreditsApi; - check balance, buy credits
    client.GroupsApi; - managing contact groups
    client.InboxApi; - managing your inbox messages and folders
    client.KeywordsApi; - check availability, rent a keyword
    client.MediaLibraryApi; - managing Media Library files
    client.MessagingApi; - send SMS/MMS/Voice broadcast messages
    client.ToolboxApi; - different helpful APIs, currently it only has a Carrier Lookup operation.

Error handling

The EzTexting Developers API uses standard HTTP response codes for responses. These HTTP codes indicate whether or not an API operation is successful.

Status Code 200 is the desired response code. A standard JSON response will follow.

Codes in the 400s range detail all of the errors a EzTexting Developer could encounter while using the API. Bad Request, Rate Limit Reached, and Unauthorized are some of the sorts of responses in the 400s block.

Codes in the 500s range are error responses from the EzTexting system. If an error has occurred anywhere in the execution of a resource that was not due to user input, a 500 response will be returned with a corresponding JSON error body. In that body will contain a message detailing what went wrong.

All API methods throw following exceptions:

  • EzTextingClientException - in case error has occurred in client

  • EzTextingApiException - in case API cannot be queried for some reason and server returned error

EzTextingApiException has errors property with details why errors has occurred.

NOTE. Currently some APIs return incorrect response codes, e.g. 403 instead of 400 or 404, this leads to wrong exception. We are working on API fixes.

Configuration

Proxy

Configuration:

    RestApiClient.getClientConfig().Add(ClientConstants.PROXY_ADDRESS_PROPERTY, "localhost:3128");
    RestApiClient.getClientConfig().Add(ClientConstants.PROXY_CREDENTIALS_PROPERTY, "proxyuser:proxypass");
    // now create client
    EzTextingClient client = new EzTextingClient("user", "pass");
    Console.WriteLine("account balance: " + client.CreditsApi.CheckBalance());

IMPORTANT. You must add proxy address property and proxy credentials (if needed) before client instantiation!

Proxy address port is optional, 8080 is used by default.

Debug & logging

In case you want to see requests/responses which client sends/receives from EzTexting platform you should copy system.diagnostics section from EzTextingApiClient.dll.config into your application’s app.config file, then it will create eztexting-api-client.log file in your work directory with debug output.

Source code debugging is available with a help of nuget symbolsource directory. Recommended configuration for Visual Studio: http://www.symbolsource.org/Public/Home/VisualStudio

Platform compatibility

Library was built and tested on OS X with mono 4.2.1 .NET 4.5 and Windows 7 x64 .NET 4.5 platform

Troubleshooting

In case you have an issue, please create a ticket at Issues page. Issue description should contain a brief info (including versions) about platform, IDE, .NET framework where this SDK is used.

What you should verify:

  • EzTextingApiClient.dll.config file is placed next to .dll assembly

  • System.Configuration is selected in project’s references window