Class: Telnyx::Resources::Dir

Inherits:
Object
  • Object
show all
Defined in:
lib/telnyx/resources/dir.rb,
lib/telnyx/resources/dir/comments.rb,
lib/telnyx/resources/dir/phone_numbers.rb,
lib/telnyx/resources/dir/phone_number_batches.rb,
sig/telnyx/resources/dir.rbs,
sig/telnyx/resources/dir/comments.rbs,
sig/telnyx/resources/dir/phone_numbers.rbs,
sig/telnyx/resources/dir/phone_number_batches.rbs

Defined Under Namespace

Classes: Comments, PhoneNumberBatches, PhoneNumbers

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Dir

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Dir.

Parameters:



349
350
351
352
353
354
 
# File 'lib/telnyx/resources/dir.rb', line 349

def initialize(client:)
  @client = client
  @comments = Telnyx::Resources::Dir::Comments.new(client: client)
  @phone_number_batches = Telnyx::Resources::Dir::PhoneNumberBatches.new(client: client)
  @phone_numbers = Telnyx::Resources::Dir::PhoneNumbers.new(client: client)
end

Instance Attribute Details

#comments ⇒ Telnyx::Resources::Dir::Comments (readonly)

Read messages from the Telnyx vetting team and reply with clarifying information.

Returns:



9
10
11
 
# File 'lib/telnyx/resources/dir.rb', line 9

def comments
  @comments
end

#phone_number_batches ⇒ Telnyx::Resources::Dir::PhoneNumberBatches (readonly)

Phone numbers are submitted to Telnyx for vetting in batches. Batches group all numbers added in a single request under the same Letter of Authorization.

Returns:



14
15
16
 
# File 'lib/telnyx/resources/dir.rb', line 14

def phone_number_batches
  @phone_number_batches
end

#phone_numbers ⇒ Telnyx::Resources::Dir::PhoneNumbers (readonly)

Associate phone numbers with a verified DIR so calls from those numbers carry the DIR's display identity.

Returns:



19
20
21
 
# File 'lib/telnyx/resources/dir.rb', line 19

def phone_numbers
  @phone_numbers
end

Instance Method Details

#delete(dir_id, request_options: {}) ⇒ nil

Delete a DIR. Failure modes: 400 if a child phone number is in a non-deletable status, 409 if the DIR has an unresolved infringement claim, 404 if the DIR is not yours.

Parameters:

  • dir_id (String) —

    The DIR id. Lowercase UUID.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)
  • request_options: (Telnyx::request_opts)

Returns:

  • (nil)

See Also:



167
168
169
170
171
172
173
174
 
# File 'lib/telnyx/resources/dir.rb', line 167

def delete(dir_id, params = {})
  @client.request(
    method: :delete,
    path: ["dir/%1$s", dir_id],
    model: NilClass,
    options: params[:request_options]
  )
end

#list(filter_call_reason_contains: nil, filter_display_name_contains: nil, filter_enterprise_id: nil, filter_expiring_at_gte: nil, filter_expiring_at_lte: nil, filter_status: nil, page_number: nil, page_size: nil, sort: nil, request_options: {}) ⇒ Telnyx::Internal::DefaultFlatPagination<Telnyx::Models::DirAPI>

Some parameter documentations has been truncated, see Models::DirListParams for more details.

Returns every DIR (Display Identity Record) you own, across all of your enterprises, as a single list. Pagination is JSON:API style (page[number], page[size], max 250). Supports filter[] query params: filter[enterprise_id], filter[status], filter[display_name][contains], filter[call_reason][contains], plus the renewal-window filters filter[expiring_at][gte] / filter[expiring_at][lte]. Sortable by created_at, updated_at, display_name, status (prefix - for descending; default -created_at).

Parameters:

  • filter_call_reason_contains (String) —

    Case-insensitive partial match on call reason.

  • filter_display_name_contains (String) —

    Case-insensitive partial match on display name.

  • filter_enterprise_id (String) —

    Filter by enterprise ID.

  • filter_expiring_at_gte (Time) —

    Return only DIRs whose expiring_at is at or after this ISO-8601 timestamp. Pai

  • filter_expiring_at_lte (Time) —

    Return only DIRs whose expiring_at is at or before this ISO-8601 timestamp.

  • filter_status (Symbol, Telnyx::Models::DirStatus) —

    Filter by DIR status.

  • page_number (Integer) —

    1-based page number. Out-of-range values return an empty page with correct meta.

  • page_size (Integer) —

    Items per page. Maximum 250; values above are clamped to 250.

  • sort (Symbol, Telnyx::Models::DirListParams::Sort) —

    Sort field. Allowed values: created_at, updated_at, display_name, status

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/telnyx/resources/dir.rb', line 132

def list(params = {})
  parsed, options = Telnyx::DirListParams.dump_request(params)
  query = Telnyx::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "dir",
    query: query.transform_keys(
      filter_call_reason_contains: "filter[call_reason][contains]",
      filter_display_name_contains: "filter[display_name][contains]",
      filter_enterprise_id: "filter[enterprise_id]",
      filter_expiring_at_gte: "filter[expiring_at][gte]",
      filter_expiring_at_lte: "filter[expiring_at][lte]",
      filter_status: "filter[status]",
      page_number: "page[number]",
      page_size: "page[size]"
    ),
    page: Telnyx::Internal::DefaultFlatPagination,
    model: Telnyx::DirAPI,
    options: options
  )
end

#list_document_types(request_options: {}) ⇒ Telnyx::Models::DirListDocumentTypesResponse

Reference list of document_type values accepted by DirCreateRequest.documents[].document_type and the infringement-contest endpoint. Each entry has a stable short_name (used in API calls) and a customer-facing description.

Parameters:

Returns:

See Also:



188
189
190
191
192
193
194
195
 
# File 'lib/telnyx/resources/dir.rb', line 188

def list_document_types(params = {})
  @client.request(
    method: :get,
    path: "dir/document_types",
    model: Telnyx::Models::DirListDocumentTypesResponse,
    options: params[:request_options]
  )
end

#list_infringement_claims(dir_id, page_number: nil, page_size: nil, request_options: {}) ⇒ Telnyx::Internal::DefaultFlatPagination<Telnyx::Models::InfringementClaim>

Some parameter documentations has been truncated, see Models::DirListInfringementClaimsParams for more details.

Return the trademark or copyright claims filed against this DIR. Each claim's status is pending (newly filed; DIR auto-suspended), contested (you have submitted contest evidence; awaiting resolution), or resolved (final). Resolution outcomes: upheld (claim accepted; DIR stays suspended/permanently_rejected), rejected (claim dismissed; DIR restored to verified), modified (partial outcome).

Parameters:

  • dir_id (String) —

    The DIR id. Lowercase UUID.

  • page_number (Integer) —

    1-based page number. Out-of-range values return an empty page with correct meta.

  • page_size (Integer) —

    Items per page. Maximum 250; values above are clamped to 250.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



220
221
222
223
224
225
226
227
228
229
230
231
 
# File 'lib/telnyx/resources/dir.rb', line 220

def list_infringement_claims(dir_id, params = {})
  parsed, options = Telnyx::DirListInfringementClaimsParams.dump_request(params)
  query = Telnyx::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["dir/%1$s/infringement_claims", dir_id],
    query: query.transform_keys(page_number: "page[number]", page_size: "page[size]"),
    page: Telnyx::Internal::DefaultFlatPagination,
    model: Telnyx::InfringementClaim,
    options: options
  )
end

#new_loa(dir_id, phone_numbers:, agent: nil, signature: nil, request_options: {}) ⇒ StringIO

Some parameter documentations has been truncated, see Models::DirNewLoaParams for more details.

Generate a pre-filled Letter of Authorization (LOA) PDF for a DIR. Enterprise identity (legal name, DBA, address, contact, website, tax id) and the DIR display name are read server-side; the caller supplies the telephone numbers to authorize, an optional Authorized Agent block, and an optional drawn signature.

When signature is omitted the PDF is returned unsigned so the customer can sign it externally and upload it via the Documents API. When signature is present the PDF embeds the supplied image, printed name, and signed-at date.

Returns application/pdf.

Parameters:

Returns:

  • (StringIO)

See Also:



262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/telnyx/resources/dir.rb', line 262

def new_loa(dir_id, params)
  parsed, options = Telnyx::DirNewLoaParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["dir/%1$s/loa", dir_id],
    headers: {"accept" => "application/pdf"},
    body: parsed,
    model: StringIO,
    options: options
  )
end

#retrieve(dir_id, request_options: {}) ⇒ Telnyx::Models::DirWrapped

Returns a single DIR by id. The enterprise is resolved server-side from the DIR id. Returns 404 if the DIR does not exist or is not yours.

Parameters:

  • dir_id (String) —

    The DIR id. Lowercase UUID.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



33
34
35
36
37
38
39
40
 
# File 'lib/telnyx/resources/dir.rb', line 33

def retrieve(dir_id, params = {})
  @client.request(
    method: :get,
    path: ["dir/%1$s", dir_id],
    model: Telnyx::DirWrapped,
    options: params[:request_options]
  )
end

#submit(dir_id, request_options: {}) ⇒ Telnyx::Models::DirWrapped

Submit a DIR for vetting. Sends the DIR back through the vetting cycle from any non-terminal status. When re-submitting from suspended or expired, the DIR's previous Branded Calling registration is torn down transactionally and its phone numbers flip back to submitted. When re-submitting from verified, the existing registration stays live throughout the new vetting cycle.

Returns 400 from submitted/in_review/permanently_rejected. Returns 409 if the DIR has an unresolved infringement claim.

Parameters:

  • dir_id (String) —

    The DIR id. Lowercase UUID.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



292
293
294
295
296
297
298
299
 
# File 'lib/telnyx/resources/dir.rb', line 292

def submit(dir_id, params = {})
  @client.request(
    method: :post,
    path: ["dir/%1$s/submit", dir_id],
    model: Telnyx::DirWrapped,
    options: params[:request_options]
  )
end

#update(dir_id, authorizer_email: nil, authorizer_name: nil, call_reasons: nil, certify_brand_is_accurate: nil, certify_ip_ownership: nil, certify_no_shaft_content: nil, display_name: nil, documents: nil, logo_url: nil, reselling: nil, request_options: {}) ⇒ Telnyx::Models::DirWrapped

Some parameter documentations has been truncated, see Models::DirUpdateParams for more details.

Edit a DIR. DIRs in draft, rejected, unsuccessful, or suspended can be edited freely: PATCH is a pure edit, status is never changed, and you re-vet by calling POST /v2/dir/{dir_id}/submit explicitly. A verified DIR can also be edited in place: a PATCH that changes any value returns the DIR to draft and branded delivery stops until you re-submit and the DIR is approved again, while a PATCH that changes nothing (an empty body or values identical to the current ones) leaves the DIR verified, so idempotent retries are safe. DIRs in any other status (submitted, in_review, expired, infringement_claimed, permanently_rejected) cannot be edited.

Parameters:

  • dir_id (String) —

    The DIR id. Lowercase UUID.

  • authorizer_email (String) —

    Contact email of the authorizer. Telnyx may send verification or infringement no

  • authorizer_name (String) —

    Name of the person at your enterprise authorizing this DIR. Must be a real indiv

  • call_reasons (Array<String>) —

    1–10 reasons your business calls customers. Validate phrasing against `POST /cal

  • certify_brand_is_accurate (Boolean) —

    Certification that the DIR information is accurate. Must be true for the DIR t

  • certify_ip_ownership (Boolean) —

    Certification of ownership of any logos/trademarks shown. Must be true for the

  • certify_no_shaft_content (Boolean) —

    Certification that this DIR is not used for SHAFT content (Sex, Hate, Alcohol, F

  • display_name (String) —

    Name shown to call recipients. 1–35 characters, no emoji, not whitespace-only.

  • documents (Array<Telnyx::Models::Document>) —

    Additional supporting documents to attach. Append-only: existing documents are n

  • logo_url (String) —

    Publicly accessible HTTPS URL (max 128 chars) to a 256x256 BMP logo (max 1 MB).

  • reselling (Boolean) —

    Set to true if your organization places calls on behalf of other enterprises (BP

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



84
85
86
87
88
89
90
91
92
93
 
# File 'lib/telnyx/resources/dir.rb', line 84

def update(dir_id, params = {})
  parsed, options = Telnyx::DirUpdateParams.dump_request(params)
  @client.request(
    method: :patch,
    path: ["dir/%1$s", dir_id],
    body: parsed,
    model: Telnyx::DirWrapped,
    options: options
  )
end

#update_infringement(dir_id, certify_brand_is_accurate:, certify_ip_ownership:, certify_no_infringement:, certify_no_shaft_content:, infringement_resolution_notes:, call_reasons: nil, display_name: nil, documents: nil, logo_url: nil, request_options: {}) ⇒ Telnyx::Models::DirWrapped

Push a fix for a DIR that is suspended with an open infringement claim back into vetting. POST /dir/{dir_id}/submit is blocked while a claim is open, so this is the customer-callable path to update the DIR's content and re-certify before Telnyx adjudicates the claim. All four certification booleans must be true. Optional content fields (display_name, logo_url, call_reasons, documents) update the DIR; documents are append-only.

Parameters:

Returns:

See Also:



335
336
337
338
339
340
341
342
343
344
 
# File 'lib/telnyx/resources/dir.rb', line 335

def update_infringement(dir_id, params)
  parsed, options = Telnyx::DirUpdateInfringementParams.dump_request(params)
  @client.request(
    method: :put,
    path: ["dir/%1$s/infringement_update", dir_id],
    body: parsed,
    model: Telnyx::DirWrapped,
    options: options
  )
end