|
1 | 1 | # twilio-csharp |
2 | 2 |
|
3 | | -[](https://github.com/twilio/twilio-csharp/actions/workflows/test-and-deploy.yml) |
4 | | -[](https://sonarcloud.io/summary/new_code?id=twilio_twilio-csharp) |
5 | | -[](https://www.nuget.org/packages/Twilio) |
6 | | -[](https://twil.io/learn-open-source) |
7 | | - |
8 | | -## Twilio REST API and TwiML Libraries for .NET |
9 | | - |
10 | | -Twilio provides a HTTP-based API for sending and receiving phone calls and text messages. Learn more on [twilio.com][apidocs]. |
11 | | - |
12 | | -More documentation for this library can be found [here][libdocs]. |
13 | | - |
14 | | -## Versions |
15 | | - |
16 | | -`twilio-csharp` uses a modified version of [Semantic Versioning](https://semver.org) for all changes. [See this document](VERSIONS.md) for details. |
17 | | - |
18 | | -### Migrate from earlier versions |
19 | | - |
20 | | -See the migration guide [here](./UPGRADE.md). Also, if you were using the `Twilio.Mvc` package, that has been replaced by the [Twilio.AspNet.Mvc][aspnet] package which is compatible with this version of the library. |
21 | | - |
22 | | -### TLS 1.2 Requirements |
23 | | - |
24 | | -New accounts and subaccounts are now required to use TLS 1.2 when accessing the REST API. ["Upgrade Required" errors](https://www.twilio.com/docs/api/errors/20426) indicate that TLS 1.0/1.1 is being used. With .NET, you can enable TLS 1.2 using this setting: |
25 | | - |
26 | | -```csharp |
27 | | -System.Net.ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12; |
28 | | -``` |
29 | | - |
30 | | -### Supported .NET versions |
31 | | - |
32 | | -This library supports .NET applications that utilize .NET6+. |
33 | | - |
34 | | -## Installation |
35 | | - |
36 | | -The best and easiest way to add the Twilio libraries to your .NET project is to use the NuGet package manager. |
37 | | - |
38 | | -### With Visual Studio IDE |
39 | | - |
40 | | -From within Visual Studio, you can use the NuGet GUI to search for and install the Twilio NuGet package. Or, as a shortcut, simply type the following command into the Package Manager Console: |
41 | | - |
42 | | -```shell |
43 | | -Install-Package Twilio |
44 | | -``` |
45 | | - |
46 | | -### With .NET Core Command Line Tools |
47 | | - |
48 | | -If you are building with the .NET Core command line tools, then you can run the following command from within your project directory: |
49 | | - |
50 | | -```shell |
51 | | -dotnet add package Twilio |
52 | | -``` |
53 | | - |
54 | | -## Sample usage |
55 | | - |
56 | | -The examples below show how to have your application initiate and outbound phone call and send an SMS message using the Twilio .NET helper library: |
57 | | - |
58 | | -```csharp |
59 | | -TwilioClient.Init("ACCOUNT_SID", "AUTH_TOKEN"); |
60 | | - |
61 | | -var call = CallResource.Create( |
62 | | - new PhoneNumber("+11234567890"), |
63 | | - from: new PhoneNumber("+10987654321"), |
64 | | - url: new Uri("https://my.twiml.here") |
65 | | -); |
66 | | -Console.WriteLine(call.Sid); |
67 | | - |
68 | | -var message = MessageResource.Create( |
69 | | - new PhoneNumber("+11234567890"), |
70 | | - from: new PhoneNumber("+10987654321"), |
71 | | - body: "Hello World!" |
72 | | -); |
73 | | -Console.WriteLine(message.Sid); |
74 | | -``` |
75 | | -## OAuth Feature for Twilio APIs |
76 | | -We are introducing Client Credentials Flow-based OAuth 2.0 authentication. This feature is currently in beta and its implementation is subject to change. |
77 | | - |
78 | | -API examples [here](https://github.com/twilio/twilio-csharp/blob/main/examples/PublicOAuthAuthentication.md) |
79 | | - |
80 | | -Organisation API examples [here](https://github.com/twilio/twilio-csharp/blob/main/examples/BearerTokenAuthentication.md) |
81 | | - |
82 | | -## Specify Region and/or Edge |
83 | | - |
84 | | -To take advantage of Twilio's [Global Infrastructure](https://www.twilio.com/docs/global-infrastructure), specify the target Region and/or Edge for the client: |
85 | | - |
86 | | -```csharp |
87 | | -TwilioClient.SetRegion("au1"); |
88 | | -TwilioClient.SetEdge("sydney"); |
89 | | -``` |
90 | | - |
91 | | -This will result in the `hostname` transforming from `api.twilio.com` to `api.sydney.au1.twilio.com`. Use appropriate client depending on the type of authentication used |
92 | | - |
93 | | -## Enable debug logging |
94 | | - |
95 | | -There are two ways to enable debug logging in the default HTTP client. You can create an environment variable called `TWILIO_LOG_LEVEL` and set it to `debug` or you can set the LogLevel variable on the client as debug: |
96 | | - |
97 | | -```csharp |
98 | | -TwilioClient.SetLogLevel("debug"); |
99 | | -``` |
100 | | - |
101 | | -## Handle exceptions |
102 | | - |
103 | | -For an example on how to handle exceptions in this helper library, please see the [Twilio documentation](https://www.twilio.com/docs/libraries/csharp-dotnet/usage-guide#handle-errors). |
104 | | - |
105 | | -## Generate TwiML |
106 | | - |
107 | | -To control phone calls, your application needs to output [TwiML][twiml]. |
108 | | - |
109 | | -```csharp |
110 | | -// TwiML classes can be created as standalone elements |
111 | | -var gather = new Gather(numDigits: 1, action: new Uri("hello-monkey-handle-key.cshtml"), method: HttpMethod.Post) |
112 | | - .Say("To speak to a real monkey, press 1. Press 2 to record your own monkey howl. Press any other key to start over."); |
113 | | - |
114 | | -// Attributes can be set directly on the object |
115 | | -gather.Timeout = 100; |
116 | | -gather.MaxSpeechTime = 200 |
117 | | - |
118 | | -// Arbitrary attributes can be set by calling set/getOption |
119 | | -var dial = new Dial().SetOption("myAttribute", 200) |
120 | | - .SetOption("newAttribute", false); |
121 | | - |
122 | | -// Or can be created and attached to a response directly using helper methods |
123 | | -var response = new VoiceResponse() |
124 | | - .Say("Hello Monkey") |
125 | | - .Play(new Uri("http://demo.twilio.com/hellomonkey/monkey.mp3")) |
126 | | - .Append(gather) |
127 | | - .Append(dial); |
128 | | - |
129 | | -// Serialize the TwiML objects to XML string |
130 | | -Console.WriteLine(response); |
131 | | - |
132 | | -/* |
133 | | -<?xml version="1.0" encoding="utf-8"?> |
134 | | -<Response> |
135 | | - <Say>Hello Monkey</Say> |
136 | | - <Play>http://demo.twilio.com/hellomonkey/monkey.mp3</Play> |
137 | | - <Gather numDigits="1" action="hello-monkey-handle-key.cshtml" method="POST" timeout="100" maxSpeechTime="200"> |
138 | | - <Say>To speak to a real monkey, press 1. Press 2 to record your own monkey howl. Press any other key to start over.</Say> |
139 | | - </Gather> |
140 | | - <Dial myAttribute="200" newAttribute="false"></Dial> |
141 | | -</Response> |
142 | | -*/ |
143 | | -``` |
144 | | - |
145 | | -## Use a custom HTTP Client |
146 | | - |
147 | | -To use a custom HTTP client with this helper library, please see the [advanced example of how to do so](./advanced-examples/custom-http-client.md). |
148 | | - |
149 | | -## Annotations |
150 | | - |
151 | | -### Beta |
152 | | -Features marked with the `[Beta]` attribute are in a beta stage and may undergo changes in future releases. Use these features with caution as they may not be stable. |
153 | | - |
154 | | -### Deprecated |
155 | | -Features marked with the `[Deprecated]` attribute are deprecated and are not encouraged to use |
156 | | - |
157 | | -### Preview |
158 | | -Features marked with the `[Preview]` attribute are in a preview stage and are intended for evaluation purposes. They are subject to change and should not be used in production without thorough testing. |
159 | | - |
160 | | -## Docker Image |
161 | | - |
162 | | -The `Dockerfile` present in this repository and its respective `twilio/twilio-csharp` Docker image are used by Twilio for testing purposes. |
163 | | - |
164 | | -You could use the docker image for building and running tests: |
165 | | - |
166 | | -```bash |
167 | | -docker build -t twiliobuild . |
168 | | -``` |
169 | | - |
170 | | -Bash: |
171 | | - |
172 | | -```bash |
173 | | -docker run -it --rm -v $(pwd):/twilio twiliobuild |
174 | | -make test |
175 | | -``` |
176 | | - |
177 | | -Powershell: |
178 | | - |
179 | | -```pwsh |
180 | | -docker run -it --rm -v ${PWD}:/twilio twiliobuild |
181 | | -make test |
182 | | -``` |
183 | | - |
184 | | -## Get support |
185 | | - |
186 | | -If you need help installing or using the library, please check the [Twilio Support Help Center](https://support.twilio.com) first, and [file a support ticket](https://twilio.com/help/contact) if you don't find an answer to your question. |
187 | | - |
188 | | -If you've instead found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo! |
189 | | - |
190 | | -[twilio]: https://www.twilio.com |
191 | | -[apidocs]: https://www.twilio.com/docs/api |
192 | | -[twiml]: https://www.twilio.com/docs/api/twiml |
193 | | -[libdocs]: https://www.twilio.com/docs/libraries/reference/twilio-csharp/ |
194 | | -[aspnet]: https://github.com/twilio/twilio-aspnet |
| 3 | +## Test Release must not be used. |
0 commit comments